Access Revocation API v1

Create and manage blacklists of Akamai Edge tokens to be revoked from accessing Adaptive Media Delivery (AMD) content.

Learn more:


Overview

If you use Adaptive Media Delivery (AMD), you can protect your content with Token Authentication. It allows you to generate unique tokens that Akamai must validate by Akamai to grant access to your media. Use this API to generate a “blacklist” 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 blacklist. The API also lets you review your blacklists and token revocation settings.

Get started

To configure this API for the first time, consider the following:

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

  • You can’t use this API and 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 scenario defined in the Segmented Media Protection behavior.

  • 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 blacklist. However, for ease of use in this documentation, we describe the use of the Property Manager interface in Akamai Control Center to do this.

Concepts

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

  • Identifiers. This collection contains the token identifiers that you’ve included in a blacklist. 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 via 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 blacklist as well as the total number of tokens the blacklist can contain.

Sample usage: Add and enable a blacklist

Use this API to generate a blacklist and revoke specific tokens. Use the Segmented Media Protection behavior in your AMD property in Property Manager to enable the blacklist. This quick example shows how to create a new blacklist here in the API, and then enable it in Property Manager in Control Center.

Step 1: Create the blacklist

  1. Add a blacklist to establish a new blacklist. Make note of the name set for the blacklist.

  2. Revoke tokens to add one or more tokens to the blacklist.

Step 2: Update your AMD property

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

  2. Ensure you add the Segmented Media Protection behavior to an applicable rule. Enable Advanced Options and set the Session-Id slider to On. See the AMD - Implementation Guide for complete configuration instructions.

  3. Set the Token Revocation slider to “On.”

  4. In the drop-down that’s revealed, select the blacklist you just created via the API (using the name you noted.)

Resources

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

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List blacklists GET /taas/v1/blacklists
Add a blacklist POST /taas/v1/blacklists
Delete a blacklist DELETE /taas/v1/blacklists/{blacklistId}
List blacklist ARL properties GET /taas/v1/blacklists/{blacklistId}/properties
Get blacklist identifier count information GET /taas/v1/blacklists/{blacklistId}/meta
List identifiers GET /taas/v1/blacklists/{blacklistId}/identifiers
Revoke tokens POST /taas/v1/blacklists/{blacklistId}/identifiers/add
Unrevoke tokens POST /taas/v1/blacklists/{blacklistId}/identifiers/remove
Get an identifier GET /taas/v1/blacklists/{blacklistId}/identifiers/{tokenId}

List blacklists

Returns a list of all blacklists.

GET /taas/v1/blacklists

Status 200 application/json

Object type: Blacklist

Download schema: getBlacklists-200.json

Response body:

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

Add a blacklist

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

POST /taas/v1/blacklists

Content-Type: application/json

Object type: Blacklist

Download schema: addBlacklistParams.json

Request body:

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

Status 202 application/json

Object type: Blacklist

Download schema: addBlacklistResponse-202.json

Response body:

{
    "id": 1,
    "name": "Baseball-ws-2019",
    "contractId": "1-ABCDE"
}
  1. If necessary, work with your account representative to obtain the Akamai contractId assigned to your instance of Access Revocation.

  2. Build a new Blacklist object. Include a unique name for the blacklist and also include your applicable contractId.

  3. POST the object to /taas/v1/blacklists.

  4. The operation responds with a Blacklist object. Store the id value from the response. (This is the blacklistId used in several other operations.)

  5. Revoke tokens to add token identifiers to the blacklist.

Delete a blacklist

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

DELETE /taas/v1/blacklists/{blacklistId}

Sample: /taas/v1/blacklists/120964235098767

Parameter Type Sample Description
URL path parameters
blacklistId Number 120964235098767 Uniquely identifies each blacklist. This corresponds to the blacklist object’s id member.

Status 204

  1. List blacklists and store the appropriate blacklist’s id as a blacklistId parameter.

  2. Make a DELETE request to /taas/v1/blacklists/{blacklistId}.

List blacklist ARL properties

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

GET /taas/v1/blacklists/{blacklistId}/properties

Sample: /taas/v1/blacklists/120964235098767/properties

Parameter Type Sample Description
URL path parameters
blacklistId Number 120964235098767 Uniquely identifies each blacklist. This corresponds to the blacklist object’s id member.

Status 200 application/json

Object type: Property

Download schema: getBlacklistARLProperties-200.json

Response body:

[
    {
        "arlFileId": 12345,
        "propertyId": 3456789,
        "propertyName": "customer-foo.com"
    },
    {
        "arlFileId": 56789,
        "propertyId": 12345678,
        "propertyName": "customer-bar.com"
    }
]
  1. List blacklists and store the appropriate blacklist’s id as a blacklistId parameter.

  2. Make a GET request to /taas/v1/blacklists/{blacklistId}/properties.

  3. Review the list of the Property objects returned.

Get blacklist identifier count information

The current count and maximum number of identifiers allowed in the blacklist.

GET /taas/v1/blacklists/{blacklistId}/meta

Sample: /taas/v1/blacklists/120964235098767/meta

Parameter Type Sample Description
URL path parameters
blacklistId Number 120964235098767 Uniquely identifies each blacklist. This corresponds to the blacklist object’s id member.

Status 200 application/json

Object type: Metadata

Download schema: metaInfo.json

Response body:

{
    "count": 500,
    "limit": 25000
}
  1. List blacklists and store the appropriate blacklist’s id as a blacklistId parameter.

  2. Make a GET request to /taas/v1/blacklists/{blacklistId}/meta.

  3. Review the list of Metadata objects that’s returned.

List identifiers

Lists all of the identifiers that belong to a specific blacklist so you can review their details.

GET /taas/v1/blacklists/{blacklistId}/identifiers

Sample: /taas/v1/blacklists/120964235098767/identifiers

Parameter Type Sample Description
URL path parameters
blacklistId Number 120964235098767 Uniquely identifies each blacklist. This corresponds to the blacklist object’s id member.

Status 200 application/json

Object type: Identifier

Download schema: getIdentifiers-200.json

Response body:

[
    {
        "id": "sqwoieksjbsdf3455",
        "ttl": 86400
    },
    {
        "id": "9082349u534589824",
        "ttl": 21600
    },
    {
        "id": "68sd899ff09sdf8787",
        "ttl": 25200
    }
]
  1. List blacklists and store the appropriate blacklist’s id as a blacklistId parameter.

  2. Make a GET request to /taas/v1/blacklists/{blacklistId}/identifiers.

  3. Review the list of Identifier objects that’s returned.

Revoke tokens

Add a set of token identifiers to a blacklist to revoke them.

POST /taas/v1/blacklists/{blacklistId}/identifiers/add

Sample: /taas/v1/blacklists/120964235098767/identifiers/add

Content-Type: application/json

Object type: Identifier

Download schema: addIdentifiersParams.json

Request body:

[
    {
        "id": "sdasd345466dg",
        "durationSeconds": 18000
    },
    {
        "id": "utrfhasdf8990",
        "durationSeconds": 3600
    }
]
Parameter Type Sample Description
URL path parameters
blacklistId Number 120964235098767 Uniquely identifies each blacklist. This corresponds to the blacklist object’s id member.

Status 200 application/json

Object type: Metadata

Download schema: metaInfo.json

Response body:

{
    "count": 500,
    "limit": 25000
}
  1. List blacklists and store the appropriate blacklist’s id as a blacklistId parameter.

  2. Obtain the session_id from the access token that you’ve configured to support Token Authentication. This value serves as the token identifier id. (See the AMD - Implementation Guide for Token Authentication instructions.)

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

  4. POST the object to /taas/v1/blacklists/{blacklistId}/identifiers/add.

  5. The operation responds with the Metadata object that shows the current count of token identifiers in the blacklist and the maximum number of identifiers it can house.

Unrevoke tokens

Remove token identifiers from a blacklist.

POST /taas/v1/blacklists/{blacklistId}/identifiers/remove

Sample: /taas/v1/blacklists/120964235098767/identifiers/remove

Content-Type: application/json

Object type: Identifier

Download schema: removeIdentifiersParams.json

Request body:

[
    "sqwoieksjbsdf3455",
    "9082349u534589824",
    "68sd899ff09sdf8787"
]
Parameter Type Sample Description
URL path parameters
blacklistId Number 120964235098767 Uniquely identifies each blacklist. This corresponds to the blacklist object’s id member.

Status 200 application/json

Object type: Metadata

Download schema: metaInfo.json

Response body:

{
    "count": 500,
    "limit": 25000
}
  1. List blacklists and store the id for the blacklist you want to unrevoke tokens. (This is its blacklistId.)

  2. Obtain the session_id from the access tokens that you want to unrevoke. This value serves as the token identifier id. (Token Authentication is described in the AMD - Implementation Guide.)

  3. Build a new Identifier object. Include the identifier id for each token identifier, and separate multiple entries with a comma.

  4. POST the object to /taas/v1/blacklists/{blacklistId}/identifiers/remove.

  5. The operation responds with the Metadata object that shows the current count of token identifiers in the blacklist and the maximum number of identifiers it can house.

Get an identifier

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

GET /taas/v1/blacklists/{blacklistId}/identifiers/{tokenId}

Sample: /taas/v1/blacklists/120964235098767/identifiers/sqwoieksjbsdf3455

Parameter Type Sample Description
URL path parameters
blacklistId Number 120964235098767 Uniquely identifies each blacklist. This corresponds to the blacklist object’s id member.
tokenId String sqwoieksjbsdf3455 The token identifier portion of the complete Akamai token. A token identifier can contain a maximum of 36 alphanumeric characters, hyphens, or underscores.

Status 200 application/json

Object type: Identifier

Download schema: getIdentifier-200.json

Response body:

{
    "id": "sqwoieksjbsdf3455",
    "ttl": 86400
}
  1. List blacklists and store the appropriate blacklist’s id as a blacklistId parameter.

  2. List identifiers and store the id for the desired token identifier.

  3. Make a GET request to /taas/v1/blacklists/{blacklistId}/identifiers/{tokenId}.

  4. Review the specific Identifier object that’s returned.

Data

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Blacklist

Parameters assigned to a blacklist during its creation.

Download schema: addBlacklistParams.json, getBlacklists-200.json

Sample GET response:

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

Blacklist members

Member Type Required Description
Blacklist: Parameters assigned to a blacklist during its creation.
contractId String The Akamai-assigned contract ID for your instance of Access Revocation.
createdBy String The Control Center login ID used to create the blacklist.
createdTime Integer The Unix epoch time when the blacklist was created.
id Integer A unique numeric identifier assigned to a blacklist.
name String A friendly name for the blacklist. The name can only contain alphanumeric and dash characters.

Property

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

Download schema: getBlacklistARLProperties-200.json

Sample GET response:

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

Property members

Member Type Description
Property: A list of Akamai resource locator (ARL) file information for each AMD property that uses a blacklist.
arlFileId Integer The unique ARL file identifier assigned to the AMD property that has Token Revocation enabled.
propertyId Integer The unique property ID assigned to the AMD property.
propertyName String The property name set for the AMD property.

Metadata

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

Download schema: metaInfo.json

Sample GET response:

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

Metadata members

Member Type Description
Metadata: The current count of token identifiers in a blacklist and the maximum number of identifiers it can house.
count Integer The total number of token identifiers in the blacklist.
limit Integer The maximum number of token identifiers that can be added to the blacklist.

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

Member Type Description
Identifier: A list of all token authentication tokens, and the parameters set for each.
id String The unique identifier assigned to the token.
ttl Integer The time to live (TTL) for the blacklist, in seconds. After this time elapses, Akamai removes this token from the blacklist.

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

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

HTTP status codes

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

Code Description
200 The operation was successful.
202 Accepted.
204 No content.
400 Bad Request.
403 Access is forbidden.
404 Not Found.
500 Internal Server Error.

Last modified: 11/25/2019