/{customer_id}/config/tokenPolicies/{token_policy_id}

Token policies are primarily 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. 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 this token 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.

This endpoint supports the following methods:

  • GET
  • PUT
  • DELETE
GET

Description

Returns information for a specific token policy.

Path Parameters

Path parameters that must be included in the request are listed in the following table:

Path Parameters
Name Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the token policy.

{token_policy_id}

string

Yes

Unique identifier of the token policy to be returned.

Sample Request (Curl)

The following command returns the token policy with the policy ID 03ded1ac-ecdb-4bb6-9c40-6b638757e9fb:

curl -X GET \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies/03ded1ac-ecdb-4bb6-9c40-6b638757e9fb \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg='

Responses

200 OK

If your call to this endpoint succeeds, you'll get back detailed information for the specified token policy:

{
    "id": "03ded1ac-ecdb-4bb6-9c40-6b638757e9fb",
    "accessTokenLifetime": 3000,
    "allowedScopes": [
        "phone"
    ],
    "refreshTokenLifetime": 7776000,
    "title": "Phone Only Token Policy",
    "_links": {
        "self": {
            "href": "/01000000-0000-3000-9000-000000000000/config/tokenPolicies/03ded1ac-ecdb-4bb6-9c40-6b638757e9fb"
        }
    }
}
PUT

Description

Modifies the specified token policy.

Path Parameters

Path parameters that must be included in the request are listed in the following table:

Path Parameters
Name Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the token policy.

{token_policy_id}

string

Yes

Unique identifier of the token policy to be modified.

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": [
    "profile",
    "phone"
],
"refreshTokenLifetime": 604800,
"title": "Documentation Token Policy"
Keys and Key Values
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 allowed 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:

"accessTokenLifetime": "1800"

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. If used, however, 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:

  • openid (required when specifying allowed scopes)
  • profile
  • email
  • address
  • phone

You must format the allowedScopes value as an array. For example:

"allowedScopes": ["openid", "email"]

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 can 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:

"refreshTokenLifetime": "864000"

Refresh tokens should have a longer lifetime than access tokens.

title

User-friendly name of the policy. For example:

"title" : "Akamai Documentation Token Policy"

This key is required. If you do not include the title then your API call will fail with the following error message:

{
  "errors": "('title',) field required"
}

Token policy titles don’t have to be unique: if you want, you can have a dozen token policies all named My Token Policy.

Sample Request Curl

The following command modifies the token policy that has the policy ID 598a1f6a-26dc-47c0-8f72-231e39ba36a7:

curl -X PUT \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies/598a1f6a-26dc-47c0-8f72-231e39ba36a7 \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessTokenLifetime": 3000,
    "allowedScopes": [
        "profile",
        "phone"
    ],
    "refreshTokenLifetime": 604800,
    "title": "Akamai Documentation Policy"
}'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back detailed information for the updated token policy:

{
    "id": "598a1f6a-26dc-47c0-8f72-231e39ba36a7",
    "accessTokenLifetime": 3000,
    "allowedScopes": [
        "profile",
        "phone"
    ],
    "refreshTokenLifetime": 604800,
    "title": "Akamai Documentation Policy",
    "_links": {
        "self": {
            "href": "/01000000-0000-3000-9000-000000000000/config/tokenPolicies/598a1f6a-26dc-47c0-8f72-231e39ba36a7"
        }
    }
}

Response Codes

The following table includes information about some of the response codes that you might encounter when calling this endpoint.

Response Codes
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:

{
    "errors": {
        "title": [
            "Missing data for required field."
        ]
    }
}
DELETE

Description

Deletes the specified token policy.

Note that you cannot delete any token policy currently assigned to an OIDC client; that’s because OIDC clients must be assigned a token policy. If you want to remove a token policy that is assigned to an OIDC client, you must first modify the OIDC client and associate it with a different token policy. Only then can the token policy be removed. If you try to delete a token policy currently assigned to one or more OIDC clients your API call will fail, and the API response will include the client IDs for all the OIDC currently associated with the policy. For example:

{
   "errors": "[\"/customers/01000000-0000-3000-9000-000000000000/clients/af4f70a3-0364-4505-94c4-8d26df86e161\",
\"/customers/01000000-0000-3000-9000-000000000000/clients/7b65f467-83fc-462e-94e7-79708e79ee18\"]\n"
}

Path Parameters

The path parameters that must be included in the request are listed in the following table:

Path Parameters
Name Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the token policy.

{token_policy_id}

string

Yes

Unique identifier of the token policy to be deleted.

Sample Request (Curl)

The following command deletes the token policy with the policy ID 03ded1ac-ecdb-4bb6-9c40-6b638757e9fb:

curl -X DELETE \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies/03ded1ac-ecdb-4bb6-9c40-6b638757e9fb \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

Responses

204 No Content

If your call to this endpoint succeeds, you will not get back a return value. Instead, you will get back the HTTP response code 204 No Content.

Response Codes

The following table includes information about some of the response codes that you might encounter when calling this endpoint.

Response Codes
Response Code Description

409

Bad request. Typically triggered if you try to delete a token policy still associated with an OIDC client.