Learn more:

• Identity and Access Management

• Identity Management API

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

Overview

The IP whitelist functionality in Akamai Control Center serves as a filtering mechanism for incoming Control Center user login requests. The IP whitelist API lets you programmatically prevent your company’s Control Center users from accessing Control Center from IP address you leave off the whitelist. This API is part of the larger Identity and Access Management application in Control Center.

Once enabled, the IP whitelist functionality lets users log in only from approved, or whitelisted, IP addresses. All other users trying to access Control Center from non-whitelisted IP addresses are blocked. The only requests that are accepted are those coming from CIDR blocks or IP addresses that you have registered and are recognized based on HTTP headers.

The IP whitelist on your company’s Control Center account is represented by an array of CIDR blocks, where each CIDR block has a unique identifier and additional descriptive information. The entire array of CIDR blocks is referred to as the IP whitelist, and allows you to perform operations on all of the CIDR blocks at once. Otherwise, you must enable or disable CIDR blocks one at a time.

You can enable or disable IP whitelist at the account level, but you can’t edit it directly. Because there is only one IP whitelist per account in Control Center, you do not need to specifically or uniquely identify it when interacting with it through this API.

Who should use this API

You should use this API if you are an administrator on your company’s Control Center account and you manage your company’s CIDR lists. You should use this CIDR list to programmatically allow user access to Control Center only from IP addresses you specify.

Getting started

• Review Get Started on tools that Akamai provides for all its APIs.

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

• This API requires admin-level grants to use. Ensure you add them to your client.

• Review the Authorize Your Client section to make sure the identity under which you provision the API can access its full range of functionality. Use the Identity Management application to expand access if necessary, or the Identity Management API as a programmatic alternative.

Resources

This section specifies the IP whitelist API’s URL resources and parameters, providing details to interact with each operation, and guidance on the workflow through the API.

The following summarizes the main set of resources available to administrators:

• IP whitelist: The account-level IP address filter that contains the set of IP addresses from which users access Control Center.

• CIDR block: A range of IP addresses. The API allows either CIDR blocks or individual IP addresses as cidrblockId parameter values. When using a CIDR block as a query parameter in this API, any slash characters included in the CIDR block must be encoded as %2F.

• State, or account status: The IP whitelist is either enabled or disabled at the account level. The View IP whitelist status operation tells you whether the IP whitelist is active on the account.

While you don’t need to validate each new CIDR block’s formatting, use the Validate CIDR blocks operation to ensure the CIDR blocks you add to your whitelist are properly formatted. If you want to validate your CIDR blocks, run the Validate CIDR blocks with the CIDR block as a query parameter before running Create a CIDR block.

Editing or deleting CIDR blocks is restricted by IP address and user permissions. Additionally, because a whitelist cannot be empty, you may not modify or delete a CIDR block that is the only element in a whitelist.

The IP whitelist on your company’s Control Center account is represented by an array of CIDR blocks, where each CIDR block has a unique identifier and additional descriptive information. The entire array of CIDR blocks is referred to as the IP whitelist, and allows you to perform operations on all of the CIDR blocks at once. Otherwise, enabling or disabling a CIDR block must be done one at a time.

The whitelist can be enabled or disabled at the account level, but it is not its own object that you can edit directly. Because there is only one IP whitelist per account in Control Center, it does not need to be specifically or uniquely identified when interacting with it through this API.

API summary

Download the RAML descriptors for this API.

List CIDR blocks

Retrieve a list of all CIDR blocks on your account’s IP whitelist. The whitelist you retrieve is for the account designated by your API client.

[
    {
        "cidrBlockId": 921,
        "enabled": true,
        "comments": "West Coast Office",
        "cidrBlock": "127.0.0.1/24",
        "createdDate": "2017-07-27T18:11:25.000Z",
        "createdBy": "johndoe",
        "modifiedDate": "2017-07-27T18:11:25.000Z",
        "modifiedBy": "johndoe",
        "actions": {
            "delete": true,
            "edit": true
        }
    },
    {
        "cidrBlockId": 6042,
        "enabled": true,
        "comments": "East Coast Office",
        "cidrBlock": "128.5.6.6/24",
        "createdDate": "2017-07-27T18:11:25.000Z",
        "createdBy": "johndoe",
        "modifiedDate": "2017-07-27T18:11:25.000Z",
        "modifiedBy": "johndoe",
        "actions": {
            "delete": true,
            "edit": false
        }
    }
]

Create a CIDR block

Add additional CIDR blocks to your account’s IP whitelist. You can only add one CIDR block at a time.

{
    "enabled": true,
    "comments": "EMEA Offices",
    "cidrBlock": "128.10.46.60/24"
}

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}

View CIDR block details

Retrieve a specific CIDR block.

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}

Modify a CIDR block

Enable or disable an existing CIDR block, or perform other edits like updating comments or update the IP address or range in the CIDR block. Note that you can only update a CIDR block if there are multiple CIDR blocks on the whitelist, if IP whitelist is enabled on the account, and you are attempting to make your changes to the CIDR block from an IP address that is on the whitelist. You cannot edit the last CIDR block in the whitelist, or the CIDR block that allows access to the current user.

{
    "enabled": true,
    "comments": "EMEA Offices",
    "cidrBlock": "128.10.46.60/24"
}

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}

Delete a CIDR block

Once you delete a CIDR block from the whitelist, any requests from IPs you just deleted fail the next time someone tries to log in from that address. Users accessing Control Center from an IP address you delete are not automatically logged out of Control Center at the time you delete the IP address. If IP whitelist filtering is enabled for the account, you cannot delete the last CIDR block in the whitelist or the CIDR block that allows access to the current user. There are no restrictions if IP whitelist filtering is disabled on the account.

Enable IP whitelist filtering

Before you enable IP whitelist filtering on your account, you must add at least one IP address to allow through. Once enabled, the whitelist cannot be empty.

Disable IP whitelist filtering

Once you disable IP whitelist filtering on your account, users are able to access Control Center regardless of their IP address, or who assigns it.

View IP whitelist status

Describes whether IP whitelist filtering is enabled or disabled on your account.

{
    "enabled": true
}

Validate CIDR blocks

Use this operation to validate the format of your CIDR blocks. Pass the CIDR block or an individual IP address through this operation as the query parameter to validate it. Any slash characters included in the CIDR block must be encoded as %2F.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

CidrBlock

This object encapsulates all members for a CIDR block in the IP whitelist data structure.

Download schema: new-ip-acl.json, ip-acl.json

Sample POST request:

{
    "enabled": true,
    "comments": "EMEA Offices",
    "cidrBlock": "128.10.46.60/24"
}

Sample GET response:

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}

CidrBlock 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

This API adheres to the HTTP Problem Details standard.

{
  "type" : "/ip-acl/error-types/1006",
  "httpStatus" : 400,
  "title" : "error creating new record",
  "detail" : "Cidr block already whitelisted",
  "instance" : "",
  "errors" : [ ]
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Last modified: 3/29/2018