Modify a token policy

Modifying a token policy is easy, mainly because there are few restrictions placed on you: unlike other Identity Cloud components (such as OIDC clients or login policies) token policies have no read-only properties. Instead, any valid property – allowedScopes, accessTokenLifetime, refreshTokenLifetime, and title – can be changed using any API call similar to this:

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

Just make sure that your property values are formatted using JSON (JavaScript Object Notation), and that those values are included in the request body of your API call.

And that’s all you need to know. When you run the preceding API call, you’ll get back updated configuration information for the policy:

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

OK, wait: there’s actually two more things you need to know. For one, when you modify a token policy, you must include the title in your API call; leave out the title and your call will fail with an error similar to this:

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

And here’s the other thing. Suppose you have a token policy configured like the following, and you want to change only the value of the accessTokenLifetime property:

You now make the following API call, changing only the value of the accessTokenLifetime property (and including title, which you have to include regardless of whether you’re changing the value or not):

curl -X PUT \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies/598a1f6a-26dc-47c0-8f72-231e39ba36a7 \
  -H 'Authorization: Bearer 03v-eeodppPrrHXXIx56pRLyDBaOldDxqEwI59MFCFGVuSkLRapzgmfwmEHyKWle' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessTokenLifetime": 3600,
    "title": "Documentation Policy"
}'

Now, let’s take a look at the policy values after you’ve run your API call:

Notice anything unusual? That’s right: even though we didn’t change the refreshTokenLifetime and the allowedScopes properties they were changed anyway. Why? Because, if you don’t explicitly include a property in your API call, that property is automatically reset to its default value. And that’s exactly what happened here: refreshTokenLifetime was reset to the default value of 7776000 and allowedScopes was reset to the default value of null. Not exactly what we were hoping for.

So how do you get around this issue? There’s actually an easy fix. If you need to modify a token policy, start by using the GET method to return the current policy values and paste those values into the request body of your PUT call. And then, before you make your call, change only those values that need to be changed. In other words, to change the value of the accessTokenLifetime property, include all the existing values in your API call, then change only accessTokenLifetime:

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

That should give you the results you were hoping for.

Incidentally, suppose you want to completely reset a policy but you can’t remember what the default values for each property are. That’s fine; you can reset a policy to the default values by including only the title in your API call:

curl -X PUT \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/tokenPolicies/598a1f6a-26dc-47c0-8f72-231e39ba36a7 \
  -H 'Authorization: Bearer 03v-eeodppPrrHXXIx56pRLyDBaOldDxqEwI59MFCFGVuSkLRapzgmfwmEHyKWle' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Documentation Policy"
}'