Token policies are used to specify token lifetimes. By default, access tokens are valid for 1 hour (3600 seconds) before they expire; you can make the access token lifetime shorter than that value but not longer than one hour. Refresh tokens are valid for 90 days (7776000 seconds), but that lifespan can either be shortened, or can be extended to as long as one year.
Token policies are also used to specify the allowed scopes for clients associated with a given policy.
Authentication
This endpoint requires token-based authentication. To obtain an access token, you must use a confidential client (using the client ID as the username and the client secret as the password) to access the /{customer_id}}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. For example, if you get back the access token Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB then your Authorization header would look like this when using Curl:
-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'
In Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field.
Methods
This endpoint supports the following methods:
- GET
- POST
GET
Description
Returns information about the token policies associated with a customer.
Path Parameters
Path parameters that must be included in the request are listed in the following table:
| Name | Type | Required | Description |
|---|---|---|---|
|
{customer_id} |
string |
Yes |
Unique identifier of the customer associated with the token policies. |
Sample Request (Curl)
The following command returns information about the token policies associated with the customer 01000000-0000-3000-9000-000000000000:
curl -X GET \
https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies \
-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'
Responses
200 OK
If your call to this endpoint succeeds, you'll get back information about all the token policies associated with the specified customer:
{
"total": 4,
"_embedded": {
"tokenPolicies": [
{
"id": "598a1f6a-26dc-47c0-8f72-231e39ba36a7",
"_links": {
"self": {
"href": "/01000000-0000-3000-9000-000000000000/config/tokenPolicies/598a1f6a-26dc-47c0-8f72-231e39ba36a7"
}
}
},
{
"id": "5b6885e2-6d56-4067-9a4b-3a90238d6b8a",
"_links": {
"self": {
"href": "/01000000-0000-3000-9000-000000000000/config/tokenPolicies/5b6885e2-6d56-4067-9a4b-3a90238d6b8a"
}
}
},
{
"id": "aee360f7-6a3c-4961-9520-3db283fd974b",
"_links": {
"self": {
"href": "/01000000-0000-3000-9000-000000000000/config/tokenPolicies/aee360f7-6a3c-4961-9520-3db283fd974b"
}
}
},
{
"id": "d0009d7e-df77-42ce-b744-80309c376886",
"_links": {
"self": {
"href": "/01000000-0000-3000-9000-000000000000/config/tokenPolicies/d0009d7e-df77-42ce-b744-80309c376886"
}
}
}
]
}
}
POST
Description
Creates a new token policy and associates that policy with a customer.
Path Parameters
Path parameters that must be included in the request are listed in the following table:
| Name | Type | Required | Description |
|---|---|---|---|
|
{customer_id} |
string |
Yes |
Unique identifier of the customer associated with the new policy. |
Request Parameters
Request parameters for this endpoint must be formatted as a JSON object and included in the body parameter of your API call. For example:
{
"accessTokenLifetime": 3000,
"allowedScopes": [
"phone"
],
"refreshTokenLifetime": 7776000,
"title": "Phone Only Token Policy"
}
The keys and key values used in the body parameter include the following:
| Key | Description |
|---|---|
|
accessTokenLifetime |
Amount of time (in seconds) that access tokens remain valid. The default value is one hour (3600 seconds), which is also the maximum lifetime for an access token. However, access token lifetimes can be set to less than one hour, with the minimum value being one minute (60 seconds). For example:
If you do not include accessTokenLifetime in your API call the value will automatically be set to 3600. |
|
allowedScopes |
Optional property that specifies the scopes that can be returned when using this token policy (see the article OpenID Connect Scopes and Claims for more information). If you leave this property out, the token policy uses the same scopes as specified in your discovery document. Scopes specified in a token policy take precedence over scopes specified in the discovery document. A token policy can return fewer scopes than the ones listed in your discovery document, but cannot return any scopes not listed in that document. Allowed values are:
You must format the allowedScopes value as an array. For example:
You can also specify scopes that can be used with configuration clients. See the article API Security for Configuration for more information. |
|
refreshTokenLifetime |
Amount of time (in seconds) that refresh tokens remain valid; the default value is 90 days (7776000 seconds). Refresh tokens have a maximum lifetime of one year (31557600 seconds), and a minimum value of one minute (60 seconds). If you do not include refreshTokenLifetime in your API call the value will automatically be set to 7776000. For example:
Refresh tokens should have a longer lifetime than access tokens. |
|
title |
User-friendly name to be assigned to the policy. For example:
This value is required. If you do not include the title then your API call will fail with the following error message:
Note that token policy titles don’t have to be unique: if you want, you can have a dozen tokens policies all named My Token Policy. |
Sample Request (Curl)
The following command creates a new token policy (Mobile Device Token Policy) for the customer 01000000-0000-3000-9000-000000000000:
curl -X POST \
https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies \
-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB' \
-H 'Content-Type: application/json' \
-d '{
"accessTokenLifetime": 3000,
"allowedScopes": [
"phone"
],
"refreshTokenLifetime": 7776000,
"title": "Mobile Device Token Policy"
}'
Responses
201 Created
If your call to this endpoint succeeds, you'll get back the policy ID of the newly-created token policy:
"03ded1ac-ecdb-4bb6-9c40-6b638757e9fb"
Response Codes
The following table includes information about some of the response codes that you might encounter when calling this endpoint.
| Response Code | Description |
|---|---|
|
400 |
Bad request. Typically indicates a syntax error; for example, you might have left off a parameter or misspelled a parameter name. Often-times the error description will help you pinpoint the problem; for example:
|