Token

1. Requesting tokens with a grant

Clients obtain access and ID tokens from the token endpoint in exchange for an OAuth 2.0 grant.

The implicit OAuth 2.0 grant (or flow) is the only one which doesn’t involve the token endpoint; with it the requested tokens are returned from the authorisation endpoint.

2. The token endpoint URL

It is advertised in the token_endpoint server metadata and has this form:

[issuer-url]/token

3. Client authentication

Confidential clients must authenticate to the Connect2id server with their registered credentials in order to make a token request, unless a self-issued JWT or SAML 2.0 bearer assertion grant is submitted (where the assertion itself authenticates the client request).

Basic authentication is the default method for registering clients.

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Clients can register for another authentication method, such as client secret POST, client secret JWT, private key JWT or mutual TLS.

Public clients (that don’t have a credential) must identify themselves with the client_id parameter.

4. Web API overview

4. Resources

4.1 /token

4.1.1 POST

Requests an ID / access / refresh token.

Clients registered for mutual TLS authentication and / or TLS sender-constrained resource access must submit their client X.509 certificate with the HTTP request.

Header parameters:

• [ Authorization ] Used for HTTP basic authentication of the client.

• [ DPop ] An optional DPoP proof JWT, to trigger a issue of an access token of type DPoP.

• Content-Type Must be set to application/x-www-form-urlencoded.

• [ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.

• [ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body:

• The request parameters depending on the OAuth 2.0 grant type:

  • Authorisation code:

    • grant_type Set to authorization_code.
    • code The code received with the authorisation response.
    • redirect_uri The value of the redirect_uri parameter included in the original authentication request.
    • [ code_verifier ] The code verifier if Proof Key of Code Exchange (PKCE) is used.
    • [ device_secret ] The device secret if OpenID Connect native SSO is used. Since v16.0.

  • Password:

    • grant_type Set to password.
    • username The resource owner username.
    • password The resource owner password.
    • [ scope ] Optional requested scope values for the access token.

  • Client credentials:

    • grant_type Set to client_credentials.
    • [ scope ] Optional requested scope values for the access token.

  • Refresh token:

    • grant_type Set to refresh_token.
    • refresh_token The refresh token issued to the client.
    • [ scope ] Optional requested scope values for the new access token. Must not include any scope values not originally granted by the resource owner, and if omitted is treated as equal to the originally granted scope.

  • JWT bearer assertion:

    • grant_type Set to urn:ietf:params:oauth:grant-type:jwt-bearer.
    • assertion The JWT assertion.
    • [ scope ] Optional requested scope values for the access token.

  • SAML 2.0 bearer assertion:

    • grant_type Set to urn:ietf:params:oauth:grant-type:saml2-bearer.
    • assertion The SAML 2.0 assertion, BASE64 URL encoded.
    • [ scope ] Optional requested scope values for the access token.

  • Token exchange:

    • grant_type Set to urn:ietf:params:oauth:grant-type:token-exchange.
    • [ resource ] Optional URI of the resource where the requested token will be used.
    • [ audience ] Optional logical name of the resource where the requested token will be used.
    • [ scope ] Optional requested scope values for the requested token.
    • [ requested_token_type ] Optional identifier for the type of the requested token.
    • subject_token Token representing the identity or authorisation of the party on behalf of whom the request is made.
    • subject_token_type Identifier for the type of the subject token.
    • [ actor_token ] Token representing the identity or authorisation of the acting party, in impersonation (act-as) or delegation (on-behalf-of) scenarios.
    • [ actor_token_type ] Identifier for the type of the actor token, required when an actor token is present.

Success:

• Code: 200

• Content-Type: application/json

• Body: {object} The token response.

Errors:

• 400 Bad Request with a token error code.
• 401 Unauthorised with a token error code.
• 500 Internal Server Error

Example token request for a confidential client with a code grant:

POST /token HTTP/1.1
Host: c2id.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Example token request for a public client with a code grant and PKCE:

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=com.example%3A%2F%2F%2Fauth
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&client_id=123

Example token request for a public client with a password grant:

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username=alice
&password=secret
&client_id=123

Example token request with a client credentials grant:

POST /token HTTP/1.1
Host: c2id.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Example response with a Bearer access token and an ID token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type"   : "Bearer",
  "expires_in"   : 3600,
  "scope"        : "openid email profile",
  "id_token"     : "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUl..."
}

5. Representations

5.1 Token response

JSON object with members (see section 5.1 of the OAuth 2.0 standard for more information):

• access_token The access token.

• token_type The type of the access token, set to Bearer, DPoP or N_A.

• [ issued_token_type ] Identifier for the type of the issued token in a OAuth 2.0 token exchange.

• expires_in The lifetime of the access token, in seconds. Guaranteed to not exceed the refresh token lifetime or refresh token maximum idle time when a refresh token is included in the response.

• scope The scope of the access token.

• [ refresh_token ] Optional refresh token, which can be used to obtain new access tokens.

• [ refresh_token_expires_in ] The remaining lifetime of the refresh token, in seconds (when an expiring refresh token is issued). Since v15.0.

• [ id_token ] Optional OpenID Connect identity token. ID tokens issued in response to a refresh token grant will have their expiration set according to the configured op.idToken.defaultLifetime.

• [ device_secret ] Optional device secret if OpenID Connect native SSO is used. Since v16.0.

Additional members may be present if included by a custom token response plugin.

Example token response containing a Bearer access token and an ID token:

{
  "access_token" : "vJkbPNUFaK4kVIMGQlEmyA.-MAquq_5yQqtae62b8i7aw",
  "token_type"   : "Bearer",
  "expires_in"   : 600,
  "scope"        : "openid email profile app:read app:write",
  "id_token"     : "eyJraWQiOiIxZTlnZGs3IiwiYWxnIjoiUl..."
}

5.2 Token type URI

URI representing the type of a token in OAuth 2.0 token exchange (see RFC 8693, section 3).

Standard types:

• urn:ietf:params:oauth:token-type:access_token – Access token.

• urn:ietf:params:oauth:token-type:jwt – A token with JWT encoding, which can potentially represent an access token or other type of token.

• urn:ietf:params:oauth:token-type:refresh_token – Refresh token.

• urn:ietf:params:oauth:token-type:id_token – OpenID Connect ID token.

• urn:ietf:params:oauth:token-type:saml1 – Base64-URL-encoded SAML 1.1 assertion.

• urn:ietf:params:oauth:token-type:saml2 – Base64-URL-encoded SAML 2.0 assertion.

5.3 Token error

JSON object with members:

• error An error code which can take one of the following values:

  • invalid_request – The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, or is otherwise malformed.
  • invalid_client – Client authentication failed, due to missing or invalid client credentials.
  • invalid_grant – The provided OAuth 2.0 grant is invalid, expired or has been revoked. May also indicate the redirect_uri parameter doesn’t match (for a code grant).
  • unauthorized_client – The client is successfully authenticated, but it’s not registered to use the submitted grant type.
  • unsupported_grant_type – The grant type is not supported by the server.
  • invalid_scope – The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
  • invalid_dpop_proof – The request includes an invalid DPoP proof JWT.

• [ error_description ] Optional text providing additional information about the error that occurred.

• [ error_uri ] Optional URI for a web page with information about the error that occurred.

Additional JSON object members may be present if set by the grant handler or a custom token response plugin.

Example token error:

{
  "error" : "invalid_request"
}

Example token error with additional information:

{
  "error"             : "invalid_request",
  "error_description" : "Missing required grant type parameters"
}

6. Errors

400 Bad Request

Invalid or denied request. See token error codes for more information.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_grant",
  "error_description" : "Bad request: Invalid or expired authorization code"
}

401 Unauthorized

The request was denied due to an invalid or missing client authentication. See token error codes for more information. The error_description is a checklist of all possible causes why the client authentication may have failed. The client_auth_id can be used to identify the exact cause.

Example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error"             : "invalid_client",
  "error_description" : "Invalid client: Possible causes may be missing /
                         invalid client_id, missing client authentication,
                         invalid or expired client secret, invalid or expired
                         JWT authentication, invalid or expired client X.509
                         certificate, or an unexpected client authentication
                         method",
  "client_auth_id"    : "cgXB4EyYViWPt6g2"
}

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error