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 your AMD property. 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 ​Akamai​ account representative and make sure that AdaptiveMediaDelivery::AccessRevocation is included on the same contract you use with AMD.

• Meet the API's prerequisites. Before you use the Access Revocation API v2 for any operation, you need to meet all of the API's requirements.

📘

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.

1 - 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:

• 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.

• 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.

• 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.

Generate a token to define the token and store its session_id value for use later in this process.

2 - Create a revocation list

You create a revocation list using the Access Revocation API.

The operation responds with a revocation list object. Store the id value from the response. This is its revocationListId.

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

📘

You can have a maximum of 10 revocation lists.

3 - Enable the revocation list in Property Manager

You need to enable and configure Token Authentication in the Segmented Media Protection behavior as normal. But, 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_idin 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.

Disable token revocation

This is relatively simple.

1. Create a new version of your property

2. In the Segmented Media Protection behavior, set Token Revocation to Off.

3. Save the new version, test it, and go live.

Delete the disabled list

You can delete the list using the Access Revocation API. Be sure to disable token revocation before you delete your revocation list. Deleting before disabling could negatively affect the delivery of your content and create unwanted errors for your end users.

4 - 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.

📘

You can have a maximum of 50,000 identifiers in a single revocation list. For best performance, ​Akamai​ recommends 5,000 identifiers or fewer per call.

Use the bulk update method (recommended)

When performing a revoke tokens operation, try to include as many identifier objects as possible, up to a maximum of 5,000 in a single call to the API. Anything more than that can create performance degradation and may result in errors and retries. 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.

📘

You're limited to a total of 60 operations per minute with the Access Revocation API v2.

FAQ