
Client Access Control API v1
Control how your origin connects to the Akamai network, adapting to changes to the CIDR blocks your connection relies on.
Learn more:
Download this API’s RAML and JSON schema descriptors.
Overview
The Client Access Control (CAC) API helps you manage access between your web assets and the edge servers on the Akamai network. With this API you can retrieve information about the CIDR blocks that currently connect your content to the Akamai network. In addition, when Akamai updates the CIDR blocks used for access, this API allows you to review the changes and send an acknowledgement to Akamai once you update your Access Control List (ACL).
Client Access Control currently only supports IPv4 CIDR blocks.
Who should use this API
Use this API as part of an automated system to dynamically synchronize your access control lists with your connection to the Akamai network. With this API, you can view the current list of CIDR blocks, and review and acknowledge updates to the CIDR block list proposed by Akamai.
You can also access this functionally from Akamai Control Center by selecting Configure ⇒ Client Access Control CIDR Lists.
Get started
Once Akamai sets up your Client Access Control configurations and notifies you that they are ready, you need to complete the following tasks before using this API:
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 Client Access Control, and set the access level to READ-WRITE.
Resources
This section provides details on each API operation.
Here’s how the API resources function:
Configurations: Before your origin can communicate with the Akamai network, Akamai sets up CAC configurations for your web assets. These configurations can include one or more hostnames that Akamai uses to connect to your network. Different configurations may specify different sets of IPv4 CIDR blocks.
Versions: Edge server IP addresses can change over time as servers are added or removed from the Akamai network. These changes usually occur once or twice within a 90 day period. When these network changes affect your ACL, Akamai proposes updates. Each proposed update to the CIDR block list is given a version number, an integer starting at zero. You specify this version number when acknowledging.
Acknowledgement: Akamai doesn’t apply a new versioned set of CIDR blocks to a CAC configuration until you acknowledge the change. Once you acknowledge the proposed list of CIDR blocks, Akamai applies the acknowledged list of CIDR blocks to the hostnames CAC configuration. Traffic then flows for those hostnames through the addresses. Keeping your local ACL synchronized with the most recent CIDR blocks ensures optimal network performance. Failure to acknowledge the updated list within 90 days of receiving it can result in reduced network performance for your web assets.
API summary
Download the RAML descriptors for this API.
Operation | Method | Endpoint |
---|---|---|
List CAC configurations | GET | /client-access-control/ |
Get a CAC configuration | GET | /client-access-control/ |
Acknowledge proposed CIDR blocks | PUT | /client-access-control/ |
List CAC configurations
Get the list of all Client Access Control (CAC) configurations to which you have access.
GET /client-access-control/
Status 200
application/json
Object type: Configuration
Download schema: configurations.json
Response Body:
[
{
"configurationId": 1060,
"name": "Example-CAC-Config",
"description": "The CAC configuration for an example application.",
"currentCidrs": {
"cidrs": [
"1.2.0.0/0"
],
"acknowledgeDate": "2016-12-08T16:42:49+0000",
"version": 1
},
"proposedCidrs": [
{
"version": 2,
"proposedDate": "2016-12-08T17:13:41+0000",
"cidrs": [
"104.67.28.248/32",
"104.68.188.248/32",
"104.76.92.248/32",
"104.78.76.248/32",
"104.81.246.248/32",
"104.82.76.248/32",
"104.83.76.248/32"
]
}
]
},
{
"configurationId": 1062,
"name": "brad test 2",
"description": "brad test 2",
"currentCidrs": {
"cidrs": [
"104.67.28.248/32",
"104.68.188.248/32",
"104.76.92.248/32",
"104.78.76.248/32",
"104.81.246.248/32"
],
"acknowledgeDate": "2016-12-08T16:42:49+0000",
"version": 2
},
"proposedCidrs": [
{
"version": 3,
"proposedDate": "2016-12-08T17:13:41+0000",
"cidrs": [
"104.81.246.248/32",
"104.82.76.248/32",
"104.83.76.248/32"
]
}
]
}
]
Get a CAC configuration
Returns the CAC configuration for a specific configurationId
.
GET /client-access-control/
Sample: /client-access-control/
Parameter | Type | Sample | Description |
---|---|---|---|
URL parameters | |||
configurationId |
Integer | 1234 |
A unique identifier for a CAC configuration. |
Status 200
application/json
Object type: Configuration
Download schema: configuration.json
Response Body:
{
"configurationId": 1060,
"name": "Example-CAC-Config",
"description": "The CAC configuration for an example application.",
"currentCidrs": {
"cidrs": [
"1.2.0.0/0"
],
"acknowledgeDate": "2016-12-08T16:42:49+0000",
"version": 1
},
"proposedCidrs": [
{
"version": 2,
"proposedDate": "2016-12-08T17:13:41+0000",
"cidrs": [
"104.67.28.248/32",
"104.68.188.248/32",
"104.76.92.248/32",
"104.78.76.248/32",
"104.81.246.248/32",
"96.6.227.191/32",
"96.7.22.43/32"
]
}
]
}
Run the List CAC configurations operation.
Choose the relevant object from the array and store its
configurationId
.Make a GET request to
/
.client-access-control/ v1/ configurations/ {configurationId}
Acknowledge proposed CIDR blocks
Once you review the
proposedCidrs
from Akamai and update your Access Control
List (ACL) accordingly, use this operation to acknowledge
the change.
PUT /client-access-control/
Sample: /client-access-control/
Parameter | Type | Sample | Description |
---|---|---|---|
URL parameters | |||
configurationId |
Integer | 1234 |
A unique identifier for a CAC configuration. |
version |
Integer | 1 |
The version of proposed CIDR blocks that you are acknowledging. |
Status 200
Run the List CAC configurations operation.
Choose the relevant object from the array and store its
configurationId
andversion
.Review the proposed CIDR blocks (
cidrs
).Update your Access Control List (ACL) with the new CIDR blocks.
Run Get a CAC configuration and verify that no new versions are available for review.
If a new version is available, review the proposed CIDR blocks (
cidrs
), and update your ACL accordingly.Make a PUT request to
/
.client-access-control/ v1/ configurations/ {configurationId}/ acknowledge/ {version}
Data
This section details the Configuration object type the CAC API provides as data. For this read-only object, the data members listed below are always present in the response object.
Configuration
Encapsulates the Client Access Control (CAC) configurations that you have access to. These configurations let your origin communicate with the Akamai network.
Download schema:
configuration.json
Sample GET:
{
"configurationId": 1060,
"name": "Example-CAC-Config",
"description": "The CAC configuration for an example application.",
"currentCidrs": {
"cidrs": [
"1.2.0.0/0"
],
"acknowledgeDate": "2016-12-08T16:42:49+0000",
"version": 1
},
"proposedCidrs": [
{
"version": 2,
"proposedDate": "2016-12-08T17:13:41+0000",
"cidrs": [
"104.67.28.248/32",
"104.68.188.248/32",
"104.76.92.248/32",
"104.78.76.248/32",
"104.81.246.248/32",
"96.6.227.191/32",
"96.7.22.43/32"
]
}
]
}
Configuration members
Member | Type | Description | |
---|---|---|---|
Configuration : Encapsulates the Client Access Control (CAC) configurations that you have access to. These configurations let your origin communicate with the Akamai network. |
|||
configurationId |
Integer | The unique ID for the CAC configuration. | |
currentCidrs |
Configuration. |
Encapsulates the current set of CIDR blocks. | |
description |
String | A description of the CAC configuration. | |
name |
String | The name of the CAC configuration. | |
proposedCidrs |
Configuration. |
Encapsulates the set of CIDR blocks proposed by Akamai. | |
Configuration.currentCidrs : Encapsulates the current set of CIDR blocks. |
|||
acknowledgeDate |
String | An ISO–8601 timestamp for when your organization last acknowledged a proposed CIDR block version. | |
cidrs |
Array | CIDR blocks used to provide this CAC configuration with access to the Akamai portal. | |
version |
Integer | The current version of CIDR blocks serving the CAC configuration. The first version is always 0 . |
|
Configuration.proposedCidrs[] : Encapsulates the set of CIDR blocks proposed by Akamai. |
|||
cidrs |
Array | CIDR blocks used to provide this CAC configuration with access to the Akamai portal. | |
proposedDate |
String | The time, in ISO–8601 format, that Akamai proposed the latest version of CIDR blocks. | |
version |
Integer | The latest version of CIDR blocks proposed. |
Errors
If you encounter a variety of errors, the Client Access Control (CAC) API responds with appropriate HTTP status codes and a response object that explains them, detailed below.
Error responses
This API responds with a JSON error object that provides details useful for debugging. For example:
{
"code": "forbidden",
"title": "Forbidden",
"details": [
{
"field": null,
"code": null,
"message": "User does not have access to resource",
"data": null
}
],
"incidentId": null,
"resolution": null,
"helpUrl": null
}
HTTP status codes
The API responds with the following set of HTTP status codes for both success and failure scenarios.
Code | Description |
---|---|
200 | The operation was successful. |
400 | Bad Request. |
403 | Access is forbidden. |
500 | Internal server error. |