Access Revocation API v1
This content only applies if you already have token-based access revocation configured using Access Revocation API v1.
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.
- Before you use the Access Revocation API for any operation, you must meet all of the requirements covered in the Get started section of the API's documentation.
- Endpoints, operations, and response data refer to a revocation list as a "blacklist."
- If necessary, work with your account representative to get
the Akamai
contractId
assigned to your instance of Access Revocation. - Build a new revocation list object. Include a unique
name
for it. It can only contain alphanumeric and dash characters. Also, include your applicablecontractId
. - POST the object to
/taas/v1/blacklists
.POST /taas/v1/blacklists { "name": "Baseball-ws-2019", "contractId": "1-ABCDE" }
id
value from the response. This is its
revocation-listId
.{
"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.
- Ensure you have
the following:
revocation-list_id
. This is theid
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 identifierid
.
- Build a new
identifier array. Add an object for each token you want
revoked. Include the identifier
id
for each, and optionally include thedurationSeconds
member to set a time to live for the revocation. After this period, tokens are "unrevoked" and can be used again to access content. - 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
Question | Answer |
---|---|
How long does it take to revoke? | Revocation time is five minutes
from the time an offending token is discovered
until Akamai begins the
"durationSeconds " TTL. |
Are there other API operations? |
Yes What's above is just the basic workflow to add access revocation. The Access Revocation API offers several more operations you can use. For example, you can review your revocation list stats and even "unrevoke" a token you've previously revoked. See the Access Revocation API v1 documentation for details. |
Can it be used with Watermarking? |
Yes When a valid user requests content, watermarking distributes segments of content based on a pattern that’s unique to that user—a "watermarking token (WMT)." If your content is pirated or redistributed, you can analyze the content and extract the user’s WMT to identify the user that originally leaked the content. You can also use access revocation to deny access to requests that include a WMT that's been flagged. See Watermarking with Access Revocation. |