The token and set its "session ID"

Access revocation uses a specific value you can include in a token—its session identifier ("session ID"). Use the process discussed in Generate the token and apply it to your content to define the token and extract its session_id value for use later in this process.

The revocation list

This is a list of session ID values associated with Token Authentication tokens. If a request includes one of these tokens, it's blocked. This helps to prevent token sharing between end users. You create a blacklist using the Access Revocation API.

1. If necessary, work with your account representative to get the Akamai contractId assigned to your instance of Access Revocation.
2. Build a new revocation list object. Include a unique name for it. It can only contain alphanumeric and dash characters. Also, include your applicable contractId.
3. POST the object to /taas/v1/blacklists.

   POST /taas/v1/blacklists
   
   {
       "name": "Baseball-ws-2019",
       "contractId": "1-ABCDE"
   }    

{
    "id": 1,
    "name": "Baseball-ws-2019",
    "contractId": "1-ABCDE"
}

Enable the revocation list in Property Manager

Configure the Token Authentication behavior as normal, but you need to set these options:

• Enable Session-Id. Set Advanced Options to "On." In the Field Carry-Over options, set the Session-Id slider to "Yes." This ensures that the session_id in the token in a request from an end user is reviewed against what you've set in your revocation list, to determine access.
• Set Token Based Access Revocation options. Set these options:
  • Token Revocation. Set this slider to "On."
  • Revocation List Name. Use this drop-down to select the revocation list you created using the API.

Revoke tokens

Once your AMD property is live on the Akamai production network and it's delivering your content, use the Access Revocation API v1 to revoke offending tokens. You add individual "identifier" objects to the revocation list that contain the unique session_id set in the offending token.

1. Ensure you have the following:
   • revocation-list_id. This is the id that was generated for your revocation list after you created it.
   • session_id. Get this from the access token that you’ve configured to support Token Authentication. This value serves as the token identifier id.
2. Build a new identifier array. Add an object for each token you want revoked. Include the identifier id for each, and optionally include the durationSeconds member to set a time to live for the revocation. After this period, tokens are "unrevoked" and can be used again to access content.
3. POST the object to /taas/v2/blacklists/{revocation-list_id}/identifiers/add.

   POST /taas/v1/blacklists/{revocation-listId}/identifiers/add
   
   [
       {
           "id": "<session_id of a token to be blocked>",
           "durationSeconds": 18000
       },
       {
           "id": "<session_id of a token to be blocked>",
           "durationSeconds": 3600
       }
   ]

The operation responds with the metadata object that shows the current count of token identifiers in the revocation list and the maximum number of identifiers it can house.

{
    "count": 500,
    "limit": 25000
}

You should use bulk update

When setting up your workflow to revoke tokens via the API, try to include as many identifier objects as possible in a single revoke operation. If you need to set up multiple operations, issue them individually over some interval of time. For example, you could set up one every 30 seconds.

FAQ