How to add Token-based Access Revocation

Token-based access revocation lets you generate a "revocation list" of specific Token Authentication tokens to block access requests that include them. This helps to prevent token sharing between end users.

Before you begin

You set up access revocation with the Segmented Media Protection behavior in an AMD property, and you also need to use the Access Revocation API for configuration. Both require the following:

  • You need to have it added to your contract. Work with your account representative to ensure your contract includes the AdaptiveMediaDelivery::AccessRevocation product.
  • The API has been updated to v2. The instructions here cover the use of this new version of the API. If you're still using v1, see Access Revocation v1.
  • Meet the v2 API's prerequisites. Before you use the Access Revocation API v2 for any operation, you need to meet all of the requirements covered in the Get started section of the API's documentation.
Note: You can't use basic access revocation if you have a custom Token Authentication scenario. A custom scenario doesn't use the default scenarios you can define using settings in the Segmented Media Protection behavior. It's typically set up by your account representative. Talk to your account representative to see if you can use access revocation.

Create a token and set its "session ID"

Access revocation uses a specific value included in a token—its session identifier ("session ID"). A session ID lets you control the level used to revoke the token. Here are a few example cases:

  1. You can use a unique session ID for each session to revoke that playback session. The stream thief will have to log back in to restart playback, and then re-share the URL with the unauthorized users all over again. This isn't a complete deterrent, but it makes it inconvenient to pirate content.
  2. You can use the specific user ID as the session ID. This blocks the specific user from accessing all content that's served through your AMD property for 24 hours.
  3. You can use a composite session ID for a specific user ID and content combination. For example, if the stream thief is sharing a live event link, he wouldn't be able to access the live event for playback himself during its duration or for 24 hours, whichever is earlier.

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.

Create a revocation list

You create a revocation list using the Access Revocation API.

  1. If necessary, work with your account representative to obtain the Akamai contractId assigned to your instance of Access Revocation.
  2. Build a new revocation list object. Include a unique name for the revocation list. It can only contain alphanumeric and dash characters. Also, include your applicable contractId.
  3. POST the object to /taas/v2/revocation-lists.
    POST /taas/v2/revocation-list
        "name": "Baseball-ws-2019",
        "contractId": "1-ABCDE"
  4. The operation responds with a revocation list object. Make note of the id value from the response. This is its revocation-list_id.
        "id": 1,
        "name": "Baseball-ws-2019",
        "contractId": "1-ABCDE"
Note: You can only have a single revocation list.

Enable the revocation list in Property Manager

You need to enable and configure the Token Authentication behavior as normal, but you need to ensure that you set the following, to enable access revocation and add your revocation list:

  • Enable Session-Id. Set Advanced Options to "On" and ensure that the Session-Id slider in the Field Carry-Over options is set 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 as follows:
    • 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 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/revocation-lists/{revocation-list_id}/identifiers/add.
    POST /taas/v2/revocation-lists/{revocation-list_id}/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
Note: You can have a maximum of 25,000 identifiers in a single revocation list.

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.

Note: You're limited to a total of 60 operations per minute with the Access Revocation API v2. See the Access Revocation API documentation for details on how rate limiting is applied.


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?


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 v2 documentation for details.

Can it be used with Watermarking?


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.