Create a token policy

Login policies aren’t hard to create, but they do require you to do a little bit of research; for example, you need to know the client ID and client secret for your owner client before you can create a login policy. Token policies are easer to create, partly because there’s much less research involved and partly because there are fewer property values that you need to worry about. As a matter of fact, the following table lists all the properties than can be configured in a token policy:

Property

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. (The minimum value is one minute: 60 seconds.) However, access token lifetimes can be set to less than one hour; for example:

"accessTokenLifetime": "1800"

If you don’t include accessTokenLifetime in your API call the value is automatically set to 3600.

allowedScopes

Optional property that specifies the scopes that can be returned when using this token policy (see the article Scopes and claims for more information). If you leave this property out the token policy uses the same scopes specified in your discovery document.

A token policy can return fewer scopes than the ones listed in your discovery document, but it can’t return any scopes not listed in that document. The allowed Identity Cloud scopes are:

  • openid (which must always be specified)
  • profile
  • email
  • address
  • phone

And keep in mind that you must format the allowedScopes value as an array. For example:

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

Note that the preceding information applies only to confidential and public clients. If you’re creating a configuration client you’ll need to work with a completely different set scopes. See the article Get an administrative access token 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 don’t include refreshTokenLifetime in your API call the value is automatically set to 7776000.

For example:

"refreshTokenLifetime": "864000"

As a general rule, refresh tokens should have a longer lifetime than access tokens. Why? Well, suppose your access tokens have a lifetime of 60 minutes but your refresh tokens have a lifetime of 30 minutes. In a case like that, your refresh token would expire before the access token does, rendering the refresh token useless.

ttitle

User-friendly title of the policy. For example:

"title" : "Akamai Documentation Token Policy"

Note that this property is required. If you leave off the title your API call fails with the following error message:

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

However, token policy titles don’t have to be unique: if you want, you can have a dozen tokens policies all named My Token Policy. (We don’t recommend that, but it works.)

When you create a token policy the only parameter you must include is title; all the other parameters are optional. For example, the following API call creates a new token policy named No Configured Values:

curl -X POST \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies/f2c8748e-7024-457c-ab48-1dd8fc3dc3b3 \
  -H 'Authorization: Bearer Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH' \
  -H 'Content-Type: application/javascript' \
  -d '{
    "title": "No Configured Values"
}'

You can get away with this because the default values are used for all parameters not specified in an API call. That means that, unless you specify differently:

  • The accessTokenLifetime value is set to 3600 seconds.
  • The refreshTokenLifetime is to 7776000 seconds.
  • The allowedScopes is set to null. (If no scopes are specified then all the scopes found in your discovery document are returned.)

Of course, you probably don’t have much need for “blank” token policies. Instead, a Curl command for creating a token policy will typically look more like this:

curl -X POST \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies \
  -H 'Authorization: Bearer Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH' \
  -H 'Content-Type: application/json' \
  -d '{
  
    "accessTokenLifetime": 3000,
    "refreshTokenLifetime": "300000",
    "allowedScopes": [
        "openid",
        "phone",
        "email"
    ],
    "title": "Akamai Documentation Token Policy"
}'

Did this page help you?