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:

  • resource: A resource indicator for selecting a specific API. HelseID will return an Access Token with the aud claim set to this value.

The following parameters may be used, but only with the use of the client_credentials, refresh_token, or token_exchange grants:

  • scope: One or more scopes, separated by spaces, as described here

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: The list of scopes issued in the access token.
  • rejected_scope: A list of requested scopes that were not included in the Access Token due to the terms of use not being signed. This value is not part of the standard Token endpoint flow, but is a specific parameter for HelseID.

The rejected_scope parameter is not part of the standard Token endpoint response. It was included by HelseID to inform the client that the Access Token is missing one or more of the requested scopes. To use these scopes the organization the client represents must first sign the required terms of use. The parameter is only relevant for multi-tenant clients that can represent multiple organizations.

Error mesages from the Token endpoint:

See this document.