/{customer_id}/config/tokenPolicies

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

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:

"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. 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 any time you specify 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 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 to be assigned to the policy. For example:

"title" : "Akamai Documentation Token Policy"

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

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

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:

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