Token#

On this page

Token is a standard endpoint⁠ (opens in a new tab) used for requesting ID Token, Access Token and Refresh Token.

In addition, BankID extends the token response with the BankID Proof token if requested.

Grant types#

The type of request (and corresponding response) is determined by the grant_type request parameter:

Authorization Code#

grant_type=authorization_code

This grant type is associated with the Authorization code flow⁠ (opens in a new tab) which requires the end-user to perform an authentication and authorization step before the client can obtain tokens.

In this context, it means a BankID authentication of the end-user via one of the Identity Providers.

Client Credentials#

grant_type=client_credentials

This grant type is associated with the Client credential flow⁠ (opens in a new tab) which is a way for the Client to obtain access tokens based on its own credentials, without involving an end-user.

Refresh Token#

grant_type=refresh_token

This grant type is used to refresh a previously issued Access Token via a corresponding Refresh Token issued along with the previous Access Token.

API#

Request#

POST [token_endpoint]

You can find the signdoc-baseurl for the appropriate environment in the OpenID Configuration.

Headers#

Content-Type: application/x-www-form-urlencoded

Authentication#

Client authentication according to supported methods

Parameters#

Authorization Code#

Parameter	Description
client_id	The client ID of the OIDC Client.
grant_type	The grant type of the request.
code	Value from response of the foregoing authorize request.
redirect_uri	`redirect_uri` used in the foregoing authorize request.
code_verifier	The code verifier used in the authorize request.

Additional parameters when private_key_jwt is used for client authentication:

Parameter	Description
client_assertion	The client assertion is a signed JWT with information for client authentication.
client_assertion_type	The type of client_assertion. This value is always `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.

Client Credentials#

Name	Description
grant_type	`client_credentials`
scope	List of scopes specifying what kind of resources you request access to.

Refresh token#

Name	Description
grant_type	`refresh_token`
refresh_token	The refresh token to refresh.
scope	Requested scopes for the new set of tokens. Note: The scopes must be identical to or narrower that the original scopes of the associated authorize request. Note that scope values are case-sensitive.

Response#

Authorization Code#

Name	Description
id_token	JWT encoded ID Token.
access_token	JWT encoded Access Token.
token_type	Always `bearer`. Will be changed to Bearer
expires_in	Life-time of access_token. Related to the `exp` claim inside the Access Token. See session handling
refresh_token	JWT encoded Refresh Token.
refresh_expires_in	Life-time of refresh_token. Related to the `exp` claim inside the Refresh Token. See session handling
not-before-policy	Keycloak specific claim
session_state	Keycloak specific claim. Deprecation notice: Will be replaced by sid
scope	Granted scopes for session.
authorization_details	Included when `authorization_details` was provided in the PAR request. Contains the original request fields plus `permission_digest`.
bankid_proof	(Deprecated) Legacy JWT encoded BankID Proof Token. Included if requested using the `bankid_proof` scope.
sid	(Upcoming) Session ID.

Example#

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI...Q",
  "expires_in" : 300,
  "refresh_expires_in" : 1800,
  "refresh_token" : "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lk...A",
  "token_type" : "bearer",
  "id_token" : "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIi..Q",
  "not-before-policy" : 0,
  "session_state" : "419320de-ae6e-479c-9f73-f7c247c52134",
  "scope" : "openid nnin_altsub profile"
}

Client Credentials#

Name	Description
access_token	JWT encoded Access Token. Standard claims with BankID specific content
token_type	Always `bearer`. Will be changed to Bearer
expires_in	Life-time of access_token. Related to the `exp` claim inside the Access Token. See session handling
refresh_expires_in	Always `0` as Client Credentials response does not contain a refresh token.
not-before-policy	Keycloak specific claim
scope	Granted scopes for the new set access token.

Example#

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2l..A",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "bearer",
  "not-before-policy": 0,
  "scope": "signdoc/read_write"
}

Refresh Token#

Same as the Authorization Code response.

Example#

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I..A",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I..U",
  "token_type": "bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2..g",
  "not-before-policy": 0,
  "session_state": "66801cef-7746-4dd6-a018-43bda5c7002b",
  "scope": "openid profile"
}