Identity Management: IP Whitelist API v1
Lets you programmatically maintain a list of whitelist IP addresses to control the set of users who can access Control Center.
Learn more:
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.
Get started
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 IDM IP Whitelist, and set the access level to ADMIN.
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.
Operation | Method | Endpoint |
---|---|---|
List CIDR blocks | GET | /identity-management/ |
Create a CIDR block | POST | /identity-management/ |
View CIDR block details | GET | /identity-management/ |
Modify a CIDR block | PUT | /identity-management/ |
Delete a CIDR block | DELETE | /identity-management/ |
Enable IP whitelist filtering | POST | /identity-management/ |
Disable IP whitelist filtering | POST | /identity-management/ |
View IP whitelist status | GET | /identity-management/ |
Validate CIDR blocks | GET | /identity-management/ |
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.
GET /identity-management/
Sample: /identity-management/
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
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
}
}
]
Optionally enable the
actions
query parameter to return what actions a user can take against each CIDR block and include it in the response.Make a GET request to
/identity-management/
.v1/ user-admin/ ip-acl/ whitelist{?actions} The response is an array of CidrBlock objects.
Create a CIDR block
Add additional CIDR blocks to your account’s IP whitelist. You can only add one CIDR block at a time.
POST /identity-management/
Content-Type: application/json
Request Body:
{
"enabled": true,
"comments": "EMEA Offices",
"cidrBlock": "128.10.46.60/24"
}
Status 200
application/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
}
}
View CIDR block details
Retrieve a specific CIDR block.
GET /identity-management/
Sample: /identity-management/
Parameter | Type | Sample | Description |
---|---|---|---|
URL 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
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
}
}
Run the List CIDR blocks operation to retrieve a list of CIDR blocks. Save the
cidrBlockId
of the CIDR block you want to view.Optionally enable the
actions
query parameter to return what actions a user can take against the CIDR block and include it in the response.Make a GET request to
/identity-management/
.v1/ user-admin/ ip-acl/ whitelist/ {cidrBlockId}{?actions} The response is a CidrBlock object.
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.
PUT /identity-management/
Sample: /identity-management/
Content-Type: application/json
Request Body:
{
"enabled": true,
"comments": "EMEA Offices",
"cidrBlock": "128.10.46.60/24"
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL parameters | |||
cidrBlockId |
Integer | 6688 |
A Unique identifier for a CIDR block. |
Status 200
application/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
}
}
Run List CIDR blocks operation to and find the relevant CIDR block and
cidrBlockID
.Modidy the CIDR block.
Make a PUT request to
/identity-management/
.v1/ user-admin/ ip-acl/ whitelist/ {cidrBlockId} The response is the modified CidrBlock object.
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.
DELETE /identity-management/
Sample: /identity-management/
Parameter | Type | Sample | Description |
---|---|---|---|
URL parameters | |||
cidrBlockId |
Integer | 6688 |
A Unique identifier for a CIDR block. |
Status 204
Run the List CIDR blocks operation with the query parameter of
actions=true
to retrieve a list of deleteable CIDR blocks. Save thecidrBlockId
of the CIDR block you want to delete.Make a DELETE request to
/identity-management/
.v1/ user-admin/ ip-acl/ whitelist/ {cidrBlockId}
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.
POST /identity-management/
Status 204
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.
POST /identity-management/
Status 204
View IP whitelist status
Describes whether IP whitelist filtering is enabled or disabled on your account.
GET /identity-management/
Status 200
application/json
Response Body:
{
"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.
GET /identity-management/
Sample: /identity-management/
Parameter | Type | Sample | Description |
---|---|---|---|
Required query parameters | |||
cidrblock |
String | 127.0.0.1/20 |
The CIDR block value you want to validate. This is not the same as a cidrBlockId . |
Status 204
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:
✓ | Member is required to be present, regardless of whether its value is empty or null . |
○ | Member is optional, and may be omitted in some cases. |
✗ | Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it’s either ignored, or causes an error. |
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
Member | Type | POST | GET | Description |
---|---|---|---|---|
actions |
CidrBlock. |
✗ | ○ | Encapsulates the actions you can take 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 the CIDR block was created. |
enabled |
Boolean | ✓ | ✓ | If false , the whitelist ignores the CIDR block as if it isn’t there. |
modifiedBy |
String | ✗ | ✓ | The user who last modified the CIDR block. |
modifiedDate |
String | ✗ | ✓ | Read-only. The ISO 8601 timestamp the CIDR block was last modified. |
CidrBlock.actions: Encapsulates the actions you can take against a CIDR block. | ||||
delete |
Boolean | ✗ | ○ | Whether you can delete this CIDR block. You may not be able to delete a CIDR block if you are trying to delete it from a non-whitelisted IP address, or if the CIDR block is the only one in the IP whitelist. |
edit |
Boolean | ✗ | ○ | Whether you can edit this CIDR block. You may not be able to edit a CIDR block if you are trying to modify it from a non-whitelisted IP address, or if the CIDR block is the only one in the IP whitelist. |
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.
Code | Description |
---|---|
200 | The operation was successful. |
201 | Resource successfully created. |
204 | Successfully processed request. |
400 | Bad Request. |
401 | Authentication failure. |
403 | Access is forbidden. |
404 | Resource not found. |
500 | Internal server error. |
502 | Platform timeout error. |
503 | Too many requests. Service is temporarily unavailable. |