# Token Endpoint (OpenID4VCI)

{% hint style="info" %}
Specifications and best practice implementations for Verifiable Credentials are currently being developed. This page is expected to be updated, closely following these developments.
{% endhint %}

The `POST` request to the token endpoint issues access tokens for credential issuance. This endpoint is an OAuth 2.0 endpoint that supports grant types for OpenID4VCI credential issuance flows.

{% hint style="info" %}
The `POST` request to the token endpoint for OpenID4VCI is an **OPTIONAL** endpoint and is part of iSHARE Framework's Verifiable Credentials support in line with **OpenID for Verifiable Credential Issuance (OpenID4VCI)**.
{% endhint %}

### Endpoint

```
POST /token
```

The URL for this endpoint is provided in the Credential Issuer Metadata (see [Credential Issuer Metadata](https://dev.ishare.eu/all-roles-common-endpoints/openid4vci-endpoints/credential-issuer-metadata-openid4vci)). This endpoint may be the same as the standard iSHARE token endpoint but supports additional grant types for credential issuance flows.

### Request model

The request body MUST be sent as `application/x-www-form-urlencoded` and contain the following parameters:

* `grant_type`\
  **String**. <mark style="color:red;">(Required)</mark>\
  OAuth 2.0 grant type. For OpenID4VCI, supported values include:
  * `authorization_code`: Used when the holder has obtained an authorization code
  * `pre-authorized_code`: Used when a pre-authorized code has been provided
* `code`\
  **String**.\
  The authorization code received from the authorization endpoint. Required when `grant_type` is `authorization_code`.
* `pre-authorized_code`\
  **String**.\
  The pre-authorized code provided by the issuer. Required when `grant_type` is `pre-authorized_code`.
* `client_id`\
  **String**.\
  The client identifier. Within iSHARE, this MUST contain a valid [Party Identifier](https://framework.ishare.eu/detailed-descriptions/functional/functional-requirements-per-role/party-identification) when applicable.
* `client_assertion_type`\
  **String**.\
  Client assertion type. Within iSHARE, MUST be equal to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` when using client assertion authentication.
* `client_assertion`\
  **String (JWT)**.\
  Client assertion JWT. Within iSHARE, MUST contain a [JWT token conforming to iSHARE specifications](https://dev.ishare.eu/reference/ishare-jwt) when using client assertion authentication.
* `redirect_uri`\
  **String**.\
  The redirect URI used in the authorization request. Required when `grant_type` is `authorization_code`.

### Example request

```
POST /token
Host: credential-issuer.ishare.eu
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=SplxlOBeZQQYbYS6WxSbIA&
redirect_uri=https://wallet.example.com/cb&
client_id=did:ishare:EU.NL.NTRLNL-10000001&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Response model

The response is a JSON object containing:

* `access_token`\
  **String**. <mark style="color:red;">(Required)</mark>\
  The access token issued by the authorization server.
* `token_type`\
  **String**. <mark style="color:red;">(Required)</mark>\
  The token type. MUST be `Bearer`.
* `expires_in`\
  **Integer**.\
  The lifetime in seconds of the access token.
* `c_nonce`\
  **String**.\
  A nonce to be used in the credential request for proof of possession.
* `c_nonce_expires_in`\
  **Integer**.\
  The lifetime in seconds of the `c_nonce`.
* `scope`\
  **String**.\
  The scope of the access token.

### Example response

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "c_nonce": "8Xz5r4k3m2",
  "c_nonce_expires_in": 300
}
```

### iSHARE-Specific Requirements

Within iSHARE, the following requirements apply:

* Clients (holder applications) MUST NOT be pre-registered. A look-up in the Participant Registry is sufficient.
* The `client_id` MUST contain a valid Party Identifier when applicable.
* Client authentication using `client_assertion` (JWT) MUST be supported and MUST conform to [iSHARE JWT specifications](https://dev.ishare.eu/reference/ishare-jwt).
* The certificate used to sign the `client_assertion` MUST be validated according to iSHARE certificate validation requirements (see [Authentication](https://gitlab.com/ishare-foundation/cab/developer-portal/-/blob/main/reference/authentication.md)).