Identity Management: IP Allowlist API v2

Maintain an allowlist of IP addresses to control which users can access Akamai Control Center.

Learn more:


Overview

The IP allowlist feature serves as a filter for Akamai Control Center user login requests. With IP allowlist, you can manage your own allowlist of IP addresses and subnetworks used to gain access to your Control Center account.

When enabled on your account, IP allowlist filters and processes your Control Center users when they log in to Control Center. Users already logged in have access until their session ends, even if the allowlist changes during that time. Removing a user’s IP address from the allowlist blocks them from logging back in to Control Center.

If you’re an administrator who manages classless inter-domain routing (CIDR) lists, use this API to programmatically maintain an allowlist of IP addresses that governs user access to your Control Center account.

This API is part of the Identity and Access Management application in Control Center. This version of the API corrects nomenclature used in the previous version.

Get started

To configure this API for the first time:

  • 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.Control Center.akamaiapis.net.

  • To enable this API, choose the API service named IP allowlist API, and set the access level to ADMIN.

API concepts

This section provides a road map of the conceptual objects you deal with when interacting with this API and provides pointers to where you can learn more.

  • IP allowlist. The account-level IP address filter that contains the allowlist. The allowlist is a set of IP addresses users access Control Center from.

  • CIDR block. A range of IP addresses. This 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, encode any slash characters as %2F. An array of CIDR blocks defines the allowlist on your Control Center account. IP allowlist lets you perform operations on all of the CIDR blocks at once, rather than enabling or disabling them one at a time.

  • State, or account status. The View IP allowlist status operation tells you whether the IP allowlist is active on the account.

API workflow

This section summarizes the API’s high-level workflow patterns. See the API summary for details on all of the API’s operations.

To use IP allowlist:

  • Enable or disable IP allowlist. Set IP allowlist availability at the account level. You don’t edit the object directly. There’s one allowlist per account in Control Center so there’s no need to specify it when interacting with it through this API. After you enable IP allowlist for your account, the only login requests accepted are those coming from CIDR blocks or IP addresses you registered and recognized based on HTTP headers. Control Center blocks users trying to access from an IP address not on the allowlist.

  • Change a CIDR block. Use the Modify a CIDR block operation to enable or disable an existing CIDR block, update comments, IP address, or range in the CIDR block. User permissions and IP addresses restrict editing or deleting CIDR blocks. Additionally, you can’t modify or delete a CIDR block if it’s the only element in the allowlist.

  • Check a CIDR block’s format. Use the Validate CIDR blocks operation to check the formatting of the CIDR blocks you add to your allowlist. To validate your CIDR blocks, run the Validate CIDR blocks with the CIDR block as a query parameter before running Create a CIDR block.

Resources

This section specifies the API’s URL resources and parameters available to administrators, provides details on how to interact with each operation, and gives guidance on the workflow through the API.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List CIDR blocks GET /identity-management/v2/user-admin/ip-acl/allowlist{?actions}
Create a CIDR block POST /identity-management/v2/user-admin/ip-acl/allowlist
View CIDR block details GET /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}{?actions}
Modify a CIDR block PUT /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}
Delete a CIDR block DELETE /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}
Enable IP allowlist POST /identity-management/v2/user-admin/ip-acl/allowlist/enable
Disable IP allowlist POST /identity-management/v2/user-admin/ip-acl/allowlist/disable
View IP allowlist status GET /identity-management/v2/user-admin/ip-acl/allowlist/status
Validate CIDR blocks GET /identity-management/v2/user-admin/ip-acl/allowlist/validate{?cidrblock}

List CIDR blocks

List all CIDR blocks on your account’s allowlist. This allowlist is for the account designated by your API client.

GET /identity-management/v2/user-admin/ip-acl/allowlist{?actions}

Sample: /identity-management/v2/user-admin/ip-acl/allowlist?actions=true

Parameter Type Sample Description
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Object type: CidrBlock

Download schema: ip-acls.json

Response body:

[
    {
        "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
        }
    }
]
  1. Optionally enable the actions query parameter to return what actions a user can take against each CIDR block and include it in the response.

  2. Make a GET request to /identity-management/v2/user-admin/ip-acl/allowlist{?actions}.

  3. The operation responds with an array of CidrBlock objects.

Create a CIDR block

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

POST /identity-management/v2/user-admin/ip-acl/allowlist

Content-Type: application/json

Object type: CidrBlock

Download schema: new-ip-acl.json

Request body:

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

Status 200 application/json

Object type: CidrBlock

Download schema: ip-acl.json

Response body:

{
    "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
    }
}
  1. Create a CidrBlock request object.

  2. Make a POST request to /identity-management/v2/user-admin/ip-acl/allowlist.

  3. The operation responds with a CidrBlock object.

View CIDR block details

Get a specific CIDR block.

GET /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}{?actions}

Sample: /identity-management/v2/user-admin/ip-acl/allowlist/6688?actions=true

Parameter Type Sample Description
URL path parameters
cidrBlockId Integer 6688 A Unique identifier for a CIDR block.
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Object type: CidrBlock

Download schema: ip-acl.json

Response body:

{
    "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
    }
}
  1. Run the List CIDR blocks operation to get a list of CIDR blocks. Save the cidrBlockId of the CIDR block you want to view.

  2. Optionally enable the actions query parameter to return what actions a user can take against the CIDR block and include it in the response.

  3. Make a GET request to /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}{?actions}.

  4. The operation responds with a CidrBlock object.

Modify a CIDR block

Enable or disable an existing CIDR block, update comments, IP address, or range in the CIDR block. Note that you can only update a CIDR block with IP allowlist enabled on the account. There are several CIDR blocks on the allowlist and your attempt to make changes to the CIDR block is from an IP address that’s on the allowlist. You can’t edit the last CIDR block in the allowlist or the CIDR block allowing access to the current user.

PUT /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}

Sample: /identity-management/v2/user-admin/ip-acl/allowlist/6688

Content-Type: application/json

Object type: CidrBlock

Download schema: new-ip-acl.json

Request body:

{
    "enabled": true,
    "comments": "EMEA Offices",
    "cidrBlock": "128.10.46.60/24"
}
Parameter Type Sample Description
URL path parameters
cidrBlockId Integer 6688 A Unique identifier for a CIDR block.

Status 200 application/json

Object type: CidrBlock

Download schema: ip-acl.json

Response body:

{
    "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
    }
}
  1. Run the List CIDR blocks operation to find the relevant CIDR block and cidrBlockID.

  2. Modify the CIDR block.

  3. Make a PUT request to /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}.

  4. The operation responds with the modified CidrBlock object.

Delete a CIDR block

After you delete a CIDR block from the allowlist, any requests from IP addresses you deleted fail the next time someone tries to log in from that address. Users accessing Control Center from an IP address you delete aren’t automatically logged out of Control Center at the time you delete the IP address. With IP allowlist enabled for the account, you can’t delete the last CIDR block in the allowlist or the CIDR block allowing access to the current user. There are no restrictions with IP allowlist disabled on the account.

DELETE /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}

Sample: /identity-management/v2/user-admin/ip-acl/allowlist/6688

Parameter Type Sample Description
URL path parameters
cidrBlockId Integer 6688 A Unique identifier for a CIDR block.

Status 204

  1. Run the List CIDR blocks operation, set the actions parameter to true for a list of deletable CIDR blocks, then save the cidrBlockId of the CIDR block you want to delete.

  2. Make a DELETE request to /identity-management/v2/user-admin/ip-acl/allowlist/{cidrBlockId}.

Enable IP allowlist

Before you enable IP allowlist on your account, add at least one IP address to allow access to Control Center. The allowlist can’t be empty with IP allowlist enabled.

POST /identity-management/v2/user-admin/ip-acl/allowlist/enable

Status 204

Disable IP allowlist

After you disable IP allowlist on your account, users can access Control Center regardless of their IP address or who assigns it.

POST /identity-management/v2/user-admin/ip-acl/allowlist/disable

Status 204

View IP allowlist status

Indicates whether IP allowlist is enabled or disabled on your account.

GET /identity-management/v2/user-admin/ip-acl/allowlist/status

Status 200 application/json

Download schema: account-status.json

Response body:

{
    "enabled": true
}

Validate CIDR blocks

Check the format of your CIDR blocks. To validate, pass the CIDR block or an individual IP address through this operation as the query parameter. Encode any slash characters as %2F.

GET /identity-management/v2/user-admin/ip-acl/allowlist/validate{?cidrblock}

Sample: /identity-management/v2/user-admin/ip-acl/allowlist/validate?cidrblock=127.0.0.1/20

Parameter Type Sample Description
Required query parameters
cidrblock String 127.0.0.1/20 The CIDR block value you want to validate. This isn’t the same as a cidrBlockId.

Status 204

Data

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

CidrBlock

Encapsulates all data sent while creating or updating a CIDR block.

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

Member Type POST GET Description
CidrBlock: Encapsulates all data sent while creating or updating a CIDR block.
actions CidrBlock.actions Encapsulates the actions you can perform against a CIDR block.
cidrBlock String The value of an IP address or IP address range.
cidrBlockId Integer Read-only. A unique identifier for a CIDR block.
comments String Descriptive text you provide for the CIDR block.
createdBy String Read-only. The user who created the CIDR block.
createdDate String Read-only. The ISO 8601 timestamp indicating when the CIDR block was created.
enabled Boolean If false, the allowlist ignores the CIDR block.
modifiedBy String The user who last modified the CIDR block.
modifiedDate String Read-only. The ISO 8601 timestamp indicating when the CIDR block was last modified.
CidrBlock.actions: Encapsulates the actions you can perform against a CIDR block.
delete Boolean Indicates whether you can delete this CIDR block. You can’t delete a CIDR block from an IP address not on the allowlist, or if the CIDR block is the only one on the allowlist.
edit Boolean Indicates whether you can edit this CIDR block. You can’t edit a CIDR block from an IP address not on the allowlist, or if the CIDR block is the only one on the allowlist.

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 a problem, it responds with an object that adheres to the HTTP problem details standard. This example shows a typical error response object.

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

HTTP status codes

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

Code Description
200 The operation was successful.
201 The resource was created successfully.
204 The request was processed successfully.
400 The system can’t understand your request, perhaps due to malformed data.
401 API authentication failure. See Get started to learn how to set up your API hostname token.
403 The client isn’t authorized to invoke the service. See Get started for information on API authorization.
404 The system couldn’t find the requested resource.
500 The platform encountered an unknown error when trying to create the resource.
502 Platform timeout error.
503 The service is temporarily unavailable.