
- Overview
- Resources
- API summary
- List blacklists (deprecated)
- Add a blacklist (deprecated)
- Delete a blacklist (deprecated)
- List blacklist ARL properties (deprecated)
- Get blacklist identifier count information (deprecated)
- List identifiers (deprecated)
- Revoke tokens (deprecated)
- Unrevoke tokens (deprecated)
- Get an identifier (deprecated)
- Data
- Errors
Access Revocation API v1
Create and manage blocklists of Akamai Edge tokens to be revoked from accessing Adaptive Media Delivery (AMD) content.
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.
NOTE: This version of the API has been deprecated. It will reach full end of service on June 1, 2021. Migrate to version 2 of the API.
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 blacklist. 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 20 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
: 20 requests per minute.X-RateLimit-Remaining
: Number of remaining requests allowed during the period.X-RateLimit-Next
: Once theX-RateLimit-Limit
has been reached, this represents the time you can issue another individual request. TheX-RateLimit-Remaining
gradually increases and becomes equal toX-RateLimit-Limit
again.
Concepts
Familiarize yourself with some of the common terms used in this API.
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 using Control Center or PAPI.
Token. This refers to the
session_id
set when you define the access token for use with Token Authentication. Thesession_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
This quick example shows how to create and apply all of the components used in a blacklist, so you can revoke tokens.
Generate a token and apply it to your content. Extract the token’s
session_id
value for use later in this process.Add a blacklist to establish a new blacklist. Make note of the name set for the blacklist.
Create a new AMD property, or access an existing one in Property Manager on Control Center.
Ensure you add the Segmented Media Protection behavior to an applicable rule. Enable Advanced Options and set the Session-Id slider to On.
Set the Token Revocation slider to On.
In the Blacklist Name drop-down, select the blacklist you created with the API.
Save the AMD property and activate it on the production network to start delivering your media.
Revoke tokens to add one or more offending tokens to the blacklist. 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.
Operation | Method | Endpoint |
---|---|---|
List blacklists (deprecated) | GET | /taas/ |
Add a blacklist (deprecated) | POST | /taas/ |
Delete a blacklist (deprecated) | DELETE | /taas/ |
List blacklist ARL properties (deprecated) | GET | /taas/ |
Get blacklist identifier count information (deprecated) | GET | /taas/ |
List identifiers (deprecated) | GET | /taas/ |
Revoke tokens (deprecated) | POST | /taas/ |
Unrevoke tokens (deprecated) | POST | /taas/ |
Get an identifier (deprecated) | GET | /taas/ |
List blacklists (deprecated)
Get a list of all blacklists.
Note: This version of the API has been deprecated. Migrate to version 2.
GET /taas/
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 (deprecated)
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.
Note: This version of the API has been deprecated. Migrate to version 2.
POST /taas/
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"
}
If necessary, work with your account representative to obtain the Akamai
contractId
assigned to your instance of Access Revocation.Build a new Blacklist object. Include a unique
name
for the blacklist and also include your applicablecontractId
.POST the object to
/taas/
.v1/ blacklists The operation responds with a Blacklist object. Store the
id
value from the response. This is theblacklistId
used in several other operations.Revoke tokens to add token identifiers to the blacklist.
Delete a blacklist (deprecated)
Delete a specific blacklist. This removes support for Access Revocation in any AMD property that may have this blacklist currently selected for use.
Note: This version of the API has been deprecated. Migrate to version 2.
DELETE /taas/
Sample: /taas/
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
List blacklists and store the appropriate blacklist’s
id
as ablacklistId
parameter.Make a DELETE request to
/taas/
.v1/ blacklists/ {blacklistId}
List blacklist ARL properties (deprecated)
Get a list of Property Manager-specific information for each AMD property that uses this blacklist.
Note: This version of the API has been deprecated. Migrate to version 2.
GET /taas/
Sample: /taas/
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"
}
]
List blacklists and store the appropriate blacklist’s
id
as ablacklistId
parameter.Make a GET request to
/taas/
.v1/ blacklists/ {blacklistId}/ properties Review the list of the Property objects returned.
Get blacklist identifier count information (deprecated)
Get the current count and maximum number of identifiers allowed in the blacklist.
Note: This version of the API has been deprecated. Migrate to version 2.
GET /taas/
Sample: /taas/
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
}
List blacklists and store the appropriate blacklist’s
id
as ablacklistId
parameter.Make a GET request to
/taas/
.v1/ blacklists/ {blacklistId}/ meta Review the list of Metadata objects that’s returned.
List identifiers (deprecated)
Get a list of all of the identifiers that belong to a specific blacklist so you can review their details.
Note: This version of the API has been deprecated. Migrate to version 2.
GET /taas/
Sample: /taas/
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
}
]
List blacklists and store the appropriate blacklist’s
id
as ablacklistId
parameter.Make a GET request to
/taas/
.v1/ blacklists/ {blacklistId}/ identifiers Review the list of Identifier objects that’s returned.
Revoke tokens (deprecated)
Add a set of token identifiers to a blacklist to revoke them.
Note: This version of the API has been deprecated. Migrate to version 2.
POST /taas/
Sample: /taas/
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
}
List blacklists and store the appropriate blacklist’s
id
as ablacklistId
parameter.Obtain the
session_id
from the access token that you’ve configured to support Token Authentication. This value serves as the token identifierid
. See the AMD Implementation Guide for Token Authentication instructions.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. Adding many identifier objects to revoke many tokens lets you bulk update in a single operation.POST the object to
/taas/
.v1/ blacklists/ {blacklistId}/ identifiers/ add
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 (deprecated)
Remove token identifiers from a blacklist.
Note: This version of the API has been deprecated. Migrate to version 2.
POST /taas/
Sample: /taas/
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
}
List blacklists and store the
id
for the blacklist you want to unrevoke tokens. Store this as theblacklistId
request parameter.Obtain the
session_id
from the access tokens that you want to unrevoke. This value serves as the token identifierid
. Token Authentication is described in the AMD Implementation Guide.Build a new Identifier object. Include the identifier
id
for each token identifier, and separate multiple entries with a comma.POST the object to
/taas/
.v1/ blacklists/ {blacklistId}/ identifiers/ remove
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 (deprecated)
Get a specific identifier that belongs to a blacklist and review its details.
Note: This version of the API has been deprecated. Migrate to version 2.
GET /taas/
Sample: /taas/
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
}
List blacklists and store the appropriate blacklist’s
id
as ablacklistId
parameter.List identifiers and store the
id
for the desired token identifier.Make a GET request to
/taas/
.v1/ blacklists/ {blacklistId}/ identifiers/ {tokenId} Review the specific Identifier object that’s returned.
Data
Download the JSON schemas for this API.
This section’s data schema tables 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 access 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 you can add 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. |