The Token endpoint

The Token endpoint is available at the path /connect/token relative to the authority. For instance, the Token endpoint in the test environment will look like this:

https://helseid-sts.test.nhn.no/connect/token

This endpoint and its use is described here.

The Token endpoint can be used to programmatically request tokens. It supports the authorization_code, client_credentials, refresh_token and token_exchange grant types.

Requests to the Token endpoint

The following parameters are required:

  • client_id: An identifier for the Client. You will receive this value from HelseID Selvbetjening.
  • client_assertion: A base64 encoded JWT signed with your private key, as described here
  • client_assertion_type: The type of the client assertion. The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
  • grant_type: The grant for the request. The following values can be used: authorization_code, client_credentials, refresh_token, or urn:ietf:params:oauth:grant-type:token-exchange.

When using the authorization_code grant, these parameters must be used:

  • code: The Authorization Code, sent from HelseID in the Authorization endpoint response
  • redirect_uri: The redirect URI, as sent to HelseID in the request to the PAR endpoint
  • code_verifier: The PKCE proof key, as hashed in the request to the PAR endpoint (the value shall not be hashed when sent in this request)

When using the refresh_token grant, this parameter must be used:

  • refresh_token: The Refresh Token string, as sent from HelseID from a previous request to the Token endpoint

The following parameters may be used (in particular when using the client_credential or token_exchange grants):

  • scope: One or more scopes, separated by spaces, as described here
  • resource: A resource indicator for selecting a specific API. HelseID will return an Access Token with the aud claim set to this value.

For parameters by the use of the token_exchange grant: see this document.

An example of use of the Token endpoint:

 POST /connect/token HTTP/1.1
 Host: helseid-sts.nhn.no
 Content-Type: application/x-www-form-urlencoded

 client_id=f4352589-549d-47ec-9844-5255f4eb0fad&
 grant_type=authorization_code&
 redirect_uri=https%3A%2F%2Fclient.example.org%2Fredirect&
 code_verifier=kaaoUXWxz64a1FIzO|4uVW2CBySgShekR5G7oyEg9Q&
 client_assertion=eyJhbGciOiJSUzI...lZ22kWJV4pHr8t&
 client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
 code=FF35789EB21464EAC9EE88260A6...672FEEA01735-1&

Response from the Token endpoint

A successful response from the Token endpoint will contain the following paramters:

  • access_token: An Access Token as a Base64 encoded JWT
  • token_type: The type of token returned. For HelseID this will either DPoP, or bearer
  • expires_in: The number of seconds until the access token expires

A successful response from the Token endpoint may also contain the following paramters:

  • identity_token: An Identity Token, as a Base64 encoded JWT, which corresponds to the current user session. This value is only returned when using the authorization_code grant.
  • refresh_token: A Refresh Token. This value is only returned when the Client requests a Refresh Token using the offline_access scope, or when using the refresh_token grant.
  • rt_expires_in: The number of seconds until the refresh token expires. This value is not part of the standard Token endpoint flow, but is a specific parameter for HelseID
  • scope: Scopes that were requested

Error mesages from the Token endpoint:

See this document.