# Token

Token is a [standard endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) used for requesting
[ID Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/id-token.md), [Access Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/access-tokens.md) and [Refresh Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/refresh-tokens.md).

In addition, BankID extends the token response with the [BankID Proof token](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/bankid-proof.md) if requested.

> **Note**
>
> You will always find the up-to-date URL for the Token Endpoint in the [OpenID Configuration](https://docs.stoe.no/bankid-oidc-provider/api/openid-configuration.md) - as `token_endpoint`.

## 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](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)
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](https://docs.stoe.no/bankid-oidc-provider/core-concepts/identity-providers.md).

### Client Credentials

```
grant_type=client_credentials
```

This grant type is associated with the [Client credential flow](https://tools.ietf.org/html/rfc6749#section-4.4)
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](https://docs.stoe.no/bankid-oidc-provider/core-concepts/access-tokens.md) via a
corresponding [Refresh Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/refresh-tokens.md) 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](https://docs.stoe.no/bankid-oidc-provider/api/openid-configuration.md).

#### Headers

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

#### Authentication

Client authentication according to [supported methods](https://docs.stoe.no/bankid-oidc-provider/core-concepts/client-authentication.md)

#### 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](https://docs.stoe.no/bankid-oidc-provider/api/authorize.md) request. |
| redirect_uri  | `redirect_uri` used in the foregoing [authorize](https://docs.stoe.no/bankid-oidc-provider/api/authorize.md) request. |
| code_verifier | The code verifier used in the [authorize](https://docs.stoe.no/bankid-oidc-provider/api/authorize.md) 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](https://docs.stoe.no/bankid-oidc-provider/core-concepts/scopes-and-claims.md) specifying what kind of resources you request access to. |

##### Refresh token

| Name          | Description                                                                                                                                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| grant_type    | `refresh_token`                                                                                                                                                                                                                                                                        |
| refresh_token | The [refresh](https://docs.stoe.no/bankid-oidc-provider/core-concepts/refresh-tokens.md) token to refresh.                                                                                                                                                                             |
| scope         | Requested [scopes](https://docs.stoe.no/bankid-oidc-provider/core-concepts/scopes-and-claims.md) 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](https://docs.stoe.no/bankid-oidc-provider/core-concepts/id-token.md).                                                                                                                                |
| access_token          | JWT encoded [Access Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/access-tokens.md).                                                                                                                       |
| token_type            | Always `bearer`. [Will be changed to Bearer](https://docs.stoe.no/bankid-oidc-provider/resources/deprecations.md)                                                                                                           |
| expires_in            | Life-time of access_token. Related to the `exp` claim inside the Access Token. See [session handling](https://docs.stoe.no/bankid-oidc-provider/core-concepts/session-handling.md)                                          |
| refresh_token         | JWT encoded [Refresh Token](https://docs.stoe.no/bankid-oidc-provider/core-concepts/refresh-tokens.md).                                                                                                                     |
| refresh_expires_in    | Life-time of refresh_token. Related to the `exp` claim inside the Refresh Token. See [session handling](https://docs.stoe.no/bankid-oidc-provider/core-concepts/session-handling.md)                                        |
| not-before-policy     | Keycloak specific claim                                                                                                                                                                                                     |
| session_state         | Keycloak specific claim. Deprecation notice: [Will be replaced by sid](https://docs.stoe.no/bankid-oidc-provider/resources/deprecations.md)                                                                                 |
| scope                 | Granted [scopes](https://docs.stoe.no/bankid-oidc-provider/core-concepts/scopes-and-claims.md) for session.                                                                                                                 |
| authorization_details | Included when [`authorization_details`](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/authorization-details.md) was provided in the PAR request. Contains the original request fields plus `permission_digest`. |
| bankid_proof          | (Deprecated) Legacy JWT encoded [BankID Proof Token](https://docs.stoe.no/bankid-oidc-provider/advanced-topics/bankid-proof.md). Included if requested using the `bankid_proof` scope.                                      |
| sid                   | (Upcoming) Session ID.                                                                                                                                                                                                      |

##### Example

```json
{
  "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](https://docs.stoe.no/bankid-oidc-provider/core-concepts/access-tokens.md).  Standard claims with BankID specific content                                |
| token_type         | Always `bearer`. [Will be changed to Bearer](https://docs.stoe.no/bankid-oidc-provider/resources/deprecations.md)                                                                  |
| expires_in         | Life-time of access_token. Related to the `exp` claim inside the Access Token. See [session handling](https://docs.stoe.no/bankid-oidc-provider/core-concepts/session-handling.md) |
| refresh_expires_in | Always `0` as Client Credentials response does not contain a refresh token.                                                                                                        |
| not-before-policy  | Keycloak specific claim                                                                                                                                                            |
| scope              | Granted [scopes](https://docs.stoe.no/bankid-oidc-provider/core-concepts/scopes-and-claims.md) for the new set access token.                                                       |

##### Example

```json
{
  "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

```json
{
  "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"
}
```