Tokens

Token types

Tokens come in different shapes and sizes. We make a distinction between opaque tokens and transparent tokens:

Token Type	Description
Opaque	Token is encrypted and consists of a random sequence of alphanumeric characters that contain no inherent meaning. The token itself does not contain any content. To obtain the content, an additional endpoint is required.
Transparent	Token is not encrypted (often encoded and signed). The token contains content, and the content can be read by anyone. Example: JWT

In web services, the two most common types of tokens are JSON Web Tokens (JWTs) and opaque tokens. A JWT token is a JSON string that contains all the claims and information it represents and is certified by a signature from the issuer. By default, it’s unencrypted, but it can be encrypted via the JSON Web Encryption (JWE) standard.

An opaque token’s format is chosen by the issuer of the token. Usually, it’s a string of numbers or characters that identifies some information in the database of the issuer. This is in contrast to JWTs, where the holder of the token can’t inspect it without contacting the issuer.

It is recommended to pass the access token within the authorisation header instead of a custom header.

For example, the Basic and Digest authentication schemes are dedicated to authentication using a username and a secret. The Bearer authentication scheme is dedicated to authentication using a token.

Token introspection endpoint

Sometimes, it can be important for a protected resource to determine the status and retrieve meta-information about a token. This should be possible by using the token introspection endpoint (RFC 7662).

Example: A backend would like to know if the token from the request contains certain scopes. In this case, it could call the introspection endpoint to retrieve this information.

Request example:

POST <host>/token/introspect
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: "Bearer" + <access token>

token=<access token to be inspected>&tokenType=<type of token>*

*tokenType is optional.

Response example:

Active token response:

200 OK
Content-Type: application/json

{
    "active": true,
    "clientId": "l238j323ds-23ij4",
    "appName": "portalApp",
    "email": "[email protected]",
    "username": "jdoe",
    "productList": "[retail, oauth]",
    "scope": "read write dolphin",
    "tokenType": "JWT",
    "expiresIn": "3425"
}

Revoked or inactive token response:

200 OK
Content-Type: application/json

{
    "active": false
}