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:


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 the Luna Control Center by selecting ConfigureClient Access Control CIDR Lists.

Getting 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 for API tools that Akamai provides.

  • Review Authorize Your Client to create your Akamai API access credentials and authorizations. As detailed in The API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

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/v1/configurations/
Get a CAC Configuration GET /client-access-control/v1/configurations/{configurationId}
Acknowledge Proposed CIDR Blocks PUT /client-access-control/v1/configurations/{configurationId}/acknowledge/{version}

List CAC configurations

Get the list of all Client Access Control (CAC) configurations to which you have access.

GET /client-access-control/v1/configurations/

Status 200 application/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/v1/configurations/{configurationId}

Sample: /client-access-control/v1/configurations/1234

Parameter Type Sample Description
URL parameters
configurationId Integer 1234 A unique identifier for a CAC configuration.

Status 200 application/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"
            ]
        }
    ]
}
  1. Run the List CAC Configurations operation.

  2. Choose the relevant object from the array and store its configurationId.

  3. 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/v1/configurations/{configurationId}/acknowledge/{version}

Sample: /client-access-control/v1/configurations/1234/acknowledge/1

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

  1. Run the List CAC Configurations operation.

  2. Choose the relevant object from the array and store its configurationId and version.

  3. Review the proposed CIDR blocks (cidrs).

  4. Update your Access Control List (ACL) with the new CIDR blocks.

  5. Run Get a CAC Configuration and verify that no new versions are available for review.

  6. If a new version is available, review the proposed CIDR blocks (cidrs), and update your ACL accordingly.

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

Download the JSON schemas for this API.

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 Required Description
configurationId Integer The unique ID for the CAC configuration.
currentCidrs Configuration.currentCidrs 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.proposedCidrs[] 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.

Last modified: 3/16/2017