Access tokens
Best practices for handling OAuth tokens
In OAuth, access tokens are opaque strings that allow a client to access the protected resource.
The exact format of access and refresh tokens is left out of scope of OAuth specification, allowing the authorization server to use the representation that fits their needs the best. Because of that, clients should not assume any particular implementation, and should treat access and refresh tokens as opaque bits of information. Clients can store tokens obtained from the authorization server, and supply them in requests to resource servers — but they must not peek inside the text content of the tokens.
Access tokens are opaque
Do not rely on the content of access and refresh tokens in the implementation of your client. Their format is not guaranteed, and can be changed without notice. This can break the interoperability of your application with Pleo.
Token Introspection
Clients can use the token introspection endpoint to to obtain information about access tokens. Clients can use this endpoint to check the validity of access tokens, and find out other information such as which resource and which scopes are associated with the token.
| Environment | Token introspection endpoint URI |
|---|---|
| Staging | https://auth.staging.pleo.io/oauth/token/introspect |
| Production | https://auth.pleo.io/oauth/token/introspect |
Introspection request
Token introspection endpoint uses basic client authentication, using client identifier and client secret.
Client calls the introspection endpoint using as HTTP POST request, with parameters sent as application/x-www-form-urlencoded data.
| Parameter | Description |
|---|---|
token | [REQUIRED] The string value of the token. |
token_type_hint | [OPTIONAL] A hint about the type of the token submitted for introspection. Either access_token or refresh_token |
Introspection response
The server responds with a JSON object in application/json format with the following top-level members.
| Member | Description |
|---|---|
active | Boolean indicator of whether or not the presented token is currently active. |
sub | Universally Unique Identifier (UUID) of a resource that the access token has authorised. |
urn:pleo:params:oauth:subject_urn | Unique Resource Name (URN) of a resource that the access token has authorised. |
exp | UNIX timestamp indicating when this token will expire. |
iat | UNIX timestamp indicating when this token was originally issued. |
client_id | Client identifier for the OAuth 2.0 client that requested this token. |
aud | Service-specific string identifier or list of string identifiers representing the intended audience for this token. |
iss | String representing the issuer of this token. |
jti | String identifier for the token. |
Example
In this example, a client with a client identifier s6BhdRkqt3 and a client secret gX1fBat3bV, issues a token introspection request, to introspect an access token with the value of mF_9.B5f-4.1JqM.
POST /oauth/token/introspect HTTP/1.1
Host: auth.staging.pleo.io
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM
Introspection response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"client_id": "s6BhdRkqt3",
"sub": "b6e0abaf-0c69-4443-b59b-908cb6aabcce",
"urn:pleo:params:oauth:subject_urn": "urn:pleo:company:b6e0abaf-0c69-4443-b59b-908cb6aabcce",
"aud": "https://external.staging.pleo.io",
"iss": "pleo.staging",
"iat": 1720706356,
"exp": 1720707256,
}
Updated 4 months ago