Learn more:

• Download this API’s RAML and JSON schema descriptors.

Overview

If you use Adaptive Media Delivery (AMD), you can protect your content with Token Authentication. Use it to generate unique tokens that Akamai validates to grant access to your media. Use this API to generate a “revocation list” of specific tokens to block access requests that include them. You can set a time to live for this revocation period to automatically “unrevoke” these tokens, or you can manually remove them from a revocation list. The API also lets you review your revocation lists and access revocation settings.

Additions to this version

We’ve made these updates with version 2 of the API:

• Increased the rate limiting for requests from 20 to 60 per minute.

• Updated terminology to remove sensitive language.

Get started

Consider these points before configuring this API for the first time:

• Work with your account representative to ensure your contract includes the AdaptiveMediaDelivery::AccessRevocation product.

• You typically can’t use access revocation if you have a unique Token Authentication scenario. A unique scenario is one that’s set up by your account representative. It’s custom and outside the default scenarios you can define using settings in the Segmented Media Protection behavior. If you have a unique scenario, contact your account rep to see if you can use access revocation.

• Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

• To enable this API, choose the API service named Token Authentication as a Service (TaaS), and set the access to READ-WRITE to perform all operations.

• You can use the Access Revocation API in conjunction with the Property Manager API (PAPI). You can use PAPI to create or update an AMD property to enable Token Revocation, and then use this API to configure your Access Revocation revocation list. Akamai recommends using the Property Manager interface in Akamai Control Center to do this, and that’s what’s covered in this documentation.

Rate limiting

The Access Revocation API imposes a rate limiting constraint of 60 requests per minute to ensure even distribution of system resources. Exceeding the limit results in a 429 error response.

The API responds with these HTTP headers to provide context over how close it’s getting to the limit:

• X-RateLimit-Limit: 60 requests per minute.

• X-RateLimit-Remaining: Number of remaining requests allowed during the period.

• X-RateLimit-Next: Once the X-RateLimit-Limit has been reached, this represents the time you can issue another individual request. The X-RateLimit-Remaining gradually increases and becomes equal to X-RateLimit-Limit again.

Concepts

Familiarize yourself with some of the common terms used in this API.

• Revocation list. A revocation list provides a way to logically group token identifiers to block their use. For example, you could create a revocation list for a specific event to block specific tokens from accessing content. The revocation list resource also has properties describing its association with a contract. Revocation lists contain the identifiers collection.

• Identifiers. This collection contains the token identifiers that you’ve included in a revocation list. The token identifier refers to the Session-Id set for the token in Property Manager. You can view this value by reviewing your AMD property in Property Manager—either using Control Center or PAPI.

• Token. This refers to the session_id set when you define the access token for use with Token Authentication. The session_id serves as the token identifier referenced throughout this documentation.

• Property. This refers to the Akamai Resource Locator (ARL) properties assigned to the AMD property that has Access Revocation enabled. These properties consist of the unique ARL file ID, the AMD property’s unique ID, and the AMD property’s name.

• Metadata. In the context of this API, this refers to the current number of tokens named in a revocation list as well as the total number of tokens the revocation list can contain.

Sample usage: add and enable a revocation list

This quick example shows how to create and apply all of the components used in a revocation list, so you can revoke tokens.

1. Generate a token and apply it to your content. Extract the token’s session_id value for use later in this process.

2. Add a revocation list to establish a new revocation list. Make note of the name set for the revocation list.

3. Create a new AMD property, or access an existing one in Property Manager on Control Center.

4. Ensure you add the Segmented Media Protection behavior to an applicable rule. Enable Advanced Options and set the Session-Id slider to On.

5. Set the Token Revocation slider to On.

6. In the Revocation List Name drop-down, select the revocation list you created with the API.

7. Save the AMD property and activate it on the production network to start delivering your media.

8. Revoke tokens to add one or more offending tokens to the revocation list. This blocks requests that include them from access.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

List revocation lists

Get a list of all revocation lists.

[
    {
        "id": 1,
        "name": "customer-revocation-list1",
        "contractId": "1-ABCDE",
        "createdTime": 1569238487,
        "createdBy": "ccare2"
    },
    {
        "id": 2,
        "name": "customer-revocation-list2",
        "contractId": "2-BCDE",
        "createdBy": "ccare2",
        "createdTime": 1569238504
    }
]

Add a revocation list

Add a new list to house token identifiers that you want revoked from access. Currently, you can only have a single revocation list. There isn’t an operation that lets you modify these settings for a revocation list, so be sure you provide the proper details when adding. However, you can revoke or unrevoke token identifiers from this revocation list, as necessary.

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

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

Delete a revocation list

Delete a specific revocation list. This removes support for Access Revocation in any AMD property that may have this revocation list currently selected for use.

List revocation list ARL properties

Get a list of Property Manager-specific information for each AMD property that uses this revocation list.

[
    {
        "arlFileId": 12345,
        "propertyId": 3456789,
        "propertyName": "customer-foo.com"
    },
    {
        "arlFileId": 56789,
        "propertyId": 12345678,
        "propertyName": "customer-bar.com"
    }
]

Get revocation list identifier count information

Get the current count and maximum number of identifiers allowed in the revocation list.

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

List identifiers

List all of the identifiers that belong to a specific revocation list so you can review their details.

[
    {
        "id": "sqwoieksjbsdf3455",
        "ttl": 86400
    },
    {
        "id": "9082349u534589824",
        "ttl": 21600
    },
    {
        "id": "68sd899ff09sdf8787",
        "ttl": 25200
    }
]

Revoke tokens

Add a set of token identifiers to a revocation list to revoke them.

[
    {
        "id": "sdasd345466dg",
        "durationSeconds": 18000
    },
    {
        "id": "utrfhasdf8990",
        "durationSeconds": 3600
    }
]

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

Unrevoke tokens

Remove token identifiers from a revocation list.

[
    "sqwoieksjbsdf3455",
    "9082349u534589824",
    "68sd899ff09sdf8787"
]

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

Get an identifier

Get a specific identifier that belongs to a revocation list and review its details.

{
    "id": "sqwoieksjbsdf3455",
    "ttl": 86400
}

Data

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Revocation-list

Parameters assigned to a revocation list during its creation.

Download schema: addRevocation-listParams.json, getRevocation-lists-200.json

Sample GET response:

[
    {
        "id": 1,
        "name": "customer-revocation-list1",
        "contractId": "1-ABCDE",
        "createdTime": 1569238487,
        "createdBy": "ccare2"
    },
    {
        "id": 2,
        "name": "customer-revocation-list2",
        "contractId": "2-BCDE",
        "createdBy": "ccare2",
        "createdTime": 1569238504
    }
]

Revocation-list members

Property

A list of Akamai resource locator (ARL) file information for each AMD property that uses a revocation list.

Download schema: getRevocation-listARLProperties-200.json

Sample GET response:

[
    {
        "arlFileId": 12345,
        "propertyId": 3456789,
        "propertyName": "customer-foo.com"
    },
    {
        "arlFileId": 56789,
        "propertyId": 12345678,
        "propertyName": "customer-bar.com"
    }
]

Property members

Metadata

The current count of token identifiers in a revocation list and the maximum number of identifiers it can house.

Download schema: metaInfo.json

Sample GET response:

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

Metadata members

Identifier

A list of all token authentication tokens, and the parameters set for each.

Download schema: getIdentifiers-200.json

Sample GET response:

[
    {
        "id": "sqwoieksjbsdf3455",
        "ttl": 86400
    },
    {
        "id": "9082349u534589824",
        "ttl": 21600
    },
    {
        "id": "68sd899ff09sdf8787",
        "ttl": 25200
    }
]

Identifier members

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

When the API encounters an error, it responds with an error code and an error message that provides details that can be useful for debugging.

This shows a typical error response when you try to access a non-existent revocation-listId.

{
  "type": "resource-not-found",
  "title": "Resource Not Found",
  "instance": "0a037412-6aac-4c7f-9e45-b29fb874db86",
  "status": 404,
  "detail": "Resource Not Found (details=[No revocation list exists with given ID 123.])"
}

HTTP status codes

The API produces this set of HTTP status codes for both success and failure scenarios: