API Keys and Traffic Management API v1

Create and manage API keys. Control your API traffic with quotas and throttling.

Learn more:

Overview

Like API Keys and Traffic Management in Akamai Control Center, this API lets you create and manage API keys that serve as unique identifiers for API consumers. API keys exist inside top-level units called key collections. At the key collection level, you can set a quota limit for the number of successful requests that individual API clients can make. You can also edit access control lists (ACLs) associated with your API endpoints and resources. Together with the API Endpoint Definition API, you can use this API to programmatically deploy your APIs on the Akamai network.

Get started

To configure this API for the first time:

  • Review the closely related API Endpoints API, in particular, the Endpoint object.

  • 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 APIKEY-MANAGER-API, and set the access level to CREDENTIAL-READ-WRITE.

API concepts

This section provides a guide to the set of resources this API makes available and provides links to where you can learn more.

  • Collection. A top-level construct that contains API keys. All keys in a collection share the quota and ACL settings specified for the collection. See the Collection object.

  • Endpoint. A set of logically related API resources. See the Endpoint object in the API Endpoint Definition API.

  • Access control list. A list of endpoints and resources that API consumers who identify with keys from a particular collection can access. See the Collection object and its dirtyACL and grantedACL members.

  • Quota. The maximum number of requests that API consumers who identify with keys from a particular collection can send to an API within a specific time period. See the Quota object for details.

  • Key. A unique identifier that enables Akamai edge servers to authenticate, track, and manage API consumers. See the Key object.

  • Tag. An additional category that you associate with an API key. You can use tags for filtering operations. See the Key object and its tags member.

  • Report. A report that displays data related to quota usage within a key collection. Two quota reports are available: one that displays the request count for a single API key over time, and another that displays the quota assigned to and quota used by selected API keys at a specific time.

  • Throttling counter. A throttling counter is an object composed of a set of conditions that, when matched by an incoming client request, cause the counter to increase. For each counter, you define a limit of allowed requests per second, and if that limit is reached, edge servers reject any subsequent requests that match the counter’s associated conditions. A throttling counter operates based on a moving average of received requests during the last 5 seconds. If the average decreases below the specified requests-per-second limit, API consumers regain the capability to make requests that match the counter’s associated conditions. See the ThrottlingCounter object.

Throttle API traffic

With this API, you can throttle your API traffic to limit the number of requests allowed per second. This prevents API consumers from dominating your API infrastructure’s back end capacity, ensuring that all API consumers can interact with your API. Before you set up API throttling, make sure you understand the possible error margin associated with throttling requests. For details, see API throttling error margin.

Control API access and usage

If you have API consumers who identify with keys from a particular collection, use these options to control access and usage of your API.

  • User quota settings determine the maximum number of requests that API consumers can send to your API within a specific time period. When the quota limit is reached, Akamai edge servers stop forwarding requests to your origin server. The traffic returns to normal after the quota reset. Use the Generate a report operation to create quota reports that help you learn about the quota usage in your key collections.

  • API throttling lets you specify counters that limit the incoming API traffic. Throttling counters increase whenever an incoming request meets their corresponding throttling conditions. These conditions can either be API keys or ACL entries such as API endpoints, resources, or HTTP methods.

  • Access control lists (ACLs) provide information about endpoints and resources accessible to API consumers.

User quotas and API throttling limit the number of requests API consumers can send to your API within a specific time period. This table shows the main differences between these features:

User quota API throttling
You can only associate a quota with a key collection. The quota limit increases whenever API consumers include API keys from that key collection in requests to your registered APIs. You can associate a throttling counter with a condition, such as an API key, any HTTP method, API resource, or API endpoint. Depending on your configuration, a throttling counter may increase whenever an incoming request meets a condition, or any combination of conditions.
You can schedule a quota window for durations ranging from one hour to one month. The time period for API throttling always equals one second.
Once a quota is full, it requires an automatic or manual reset to allow any subsequent requests with a given API key. Throttling doesn’t require a reset. It operates based on a moving average. If a throttling counter reaches its limit, an API consumer needs to wait five seconds before making another request.

API workflow

This section summarizes the API’s workflow patterns to create and manage API keys on the Akamai platform. See the API summary for details on all operations. For details about the data objects the API exchanges, see the Data section.

To start, group keys into manageable collections and perform these basic operations on keys inside a collection:

  1. Create or generate keys

  2. Import keys

  3. Edit information about keys

  4. Revoke and restore keys

  5. Move keys to a new collection

  6. Filter and sort keys according to various criteria

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Collections  
List key collections GET /apikey-manager-api/v1/collections
Create a key collection POST /apikey-manager-api/v1/collections
Get a key collection GET /apikey-manager-api/v1/collections/{collectionId}
Edit a key collection PUT /apikey-manager-api/v1/collections/{collectionId}
Delete a key collection DELETE /apikey-manager-api/v1/collections/{collectionId}
List collection endpoints GET /apikey-manager-api/v1/collections/{collectionId}/endpoints
Edit an ACL PUT /apikey-manager-api/v1/collections/{collectionId}/acl
Edit quota settings PUT /apikey-manager-api/v1/collections/{collectionId}/quota
Keys  
List keys GET /apikey-manager-api/v1/keys{?collectionId,filter,pageNumber,keyType,pageSize,sortDirection,sortColumn}
Create keys POST /apikey-manager-api/v1/keys
Get a key GET /apikey-manager-api/v1/keys/{keyId}
Edit a key PUT /apikey-manager-api/v1/keys/{keyId}
Import keys POST /apikey-manager-api/v1/keys/import
Generate keys POST /apikey-manager-api/v1/keys/generate
Move keys POST /apikey-manager-api/v1/keys/move
Revoke keys POST /apikey-manager-api/v1/keys/revoke
Restore revoked keys POST /apikey-manager-api/v1/keys/restore
Reset key quota POST /apikey-manager-api/v1/keys/quota-reset
Tags  
List tags GET /apikey-manager-api/v1/tags
Reports  
Generate a report POST /apikey-manager-api/v1/reports/{reportName}/versions/{reportVersion}/report-data{?start,end,interval}
Throttling counters  
List throttling counters GET /apikey-manager-api/v1/counters
Create a throttling counter POST /apikey-manager-api/v1/counters
Get a throttling counter GET /apikey-manager-api/v1/counters/{counterId}
Edit a throttling counter PUT /apikey-manager-api/v1/counters/{counterId}
Delete a throttling counter DELETE /apikey-manager-api/v1/counters/{counterId}
List counter endpoints GET /apikey-manager-api/v1/counters/{counterId}/endpoints
List counter keys GET /apikey-manager-api/v1/counters/{counterId}/keys

List key collections

Returns information about all collections available for the current contract and group.

GET /apikey-manager-api/v1/collections

Status 200 application/json

Object type: Collection

Download schema: keyCollectionListDto-schema.json

Response body:

[
    {
        "id": 108051,
        "name": "Bookstore Access",
        "description": "A collection with API keys for use by the Bookstore API standard users.",
        "keyCount": 21,
        "contractId": "M-297UAQ5",
        "groupId": 110202,
        "dirty": false,
        "grantedACL": [
            "ENDPOINT-418250",
            "ENDPOINT-447203",
            "METHOD-106349",
            "RESOURCE-79491",
            "METHOD-106350"
        ],
        "dirtyACL": [
            "ENDPOINT-418250",
            "ENDPOINT-447203",
            "METHOD-106349",
            "RESOURCE-79491",
            "METHOD-106350"
        ],
        "quota": {
            "enabled": true,
            "value": 100,
            "interval": "HOUR_1",
            "headers": {
                "denyLimitHeaderShown": true,
                "denyRemainingHeaderShown": true,
                "denyNextHeaderShown": true,
                "allowLimitHeaderShown": true,
                "allowRemainingHeaderShown": true,
                "allowResetHeaderShown": true
            }
        }
    },
    {
        "id": 108052,
        "name": "Bookstore Premium Access",
        "description": "A collection with API keys for use by the Bookstore API premium users.",
        "keyCount": 2,
        "contractId": "M-297UAQ5",
        "groupId": 110202,
        "dirty": false,
        "grantedACL": [
            "ENDPOINT-418250",
            "ENDPOINT-447203",
            "ENDPOINT-447205",
            "ENDPOINT-447210",
            "METHOD-106349",
            "METHOD-106350",
            "METHOD-106351",
            "METHOD-106352"
        ],
        "dirtyACL": [],
        "quota": {
            "enabled": false,
            "value": 100,
            "interval": "HOUR_1",
            "headers": {
                "denyLimitHeaderShown": true,
                "denyRemainingHeaderShown": true,
                "denyNextHeaderShown": true,
                "allowLimitHeaderShown": true,
                "allowRemainingHeaderShown": true,
                "allowResetHeaderShown": true
            }
        }
    }
]

Create a key collection

Creates an empty collection under the selected contract and group.

POST /apikey-manager-api/v1/collections

Content-Type: application/json

Object type: Collection

Download schema: keyCollectionDto-schema.json

Request body:

{
    "name": "Bookstore Premium Access",
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "description": "A collection with API keys for use by the Bookstore API premium users."
}

Status 201 application/json

Headers:

Location: /apikey-manager-api/v1/collections/128000

Object type: Collection

Download schema: keyCollectionDto-schema.json

Response body:

{
    "id": 108053,
    "name": "Bookstore Premium Access",
    "description": "A collection with API keys for use by the Bookstore API premium users.",
    "keyCount": 0,
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "dirty": false,
    "grantedACL": [],
    "dirtyACL": [],
    "quota": {
        "enabled": false,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}

  1. If you don’t already have contractId and groupId values, run the List contracts and groups operation in the API Endpoints API.

  2. From the response array, choose the appropriate pairing of contract and group, and store its contractId and groupId values.

  3. Build a Collection object by specifying the unique name, contractId, and groupId values.

  4. Optionally specify the description value.

  5. POST the object to /apikey-manager-api/v1/collections.

The response reflects back the complete Collection object, from which you can store the id value. You can access the newly created collection at the URL specified in the location response header.

Get a key collection

Returns information about a collection.

GET /apikey-manager-api/v1/collections/{collectionId}

Sample: /apikey-manager-api/v1/collections/12345

Parameter Type Sample Description
URL path parameters
collectionId Integer 12345 The unique identifier for the collection.

Status 200 application/json

Object type: Collection

Download schema: keyCollectionDto-schema.json

Response body:

{
    "id": 108051,
    "name": "Bookstore Access",
    "description": "A collection with API keys for use by the Bookstore API standard users.",
    "keyCount": 21,
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "dirty": false,
    "grantedACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "dirtyACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "quota": {
        "enabled": true,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}

  1. If you don’t already have an id value of the appropriate Collection object, run the List key collections operation.

  2. Select the appropriate collection from the returned array and store its id.

  3. Make a GET request to /apikey-manager-api/v1/collections/{collectionId}.

The response is a Collection object.

Edit a key collection

Updates the name and description of a collection.

PUT /apikey-manager-api/v1/collections/{collectionId}

Sample: /apikey-manager-api/v1/collections/12345

Content-Type: application/json

Object type: Collection

Download schema: keyCollectionDto-schema.json

Request body:

{
    "id": 108051,
    "name": "Bookstore Access",
    "description": "A collection with API keys for use by the Bookstore API standard users.",
    "keyCount": 21,
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "dirty": false,
    "grantedACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "dirtyACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "quota": {
        "enabled": true,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}
Parameter Type Sample Description
URL path parameters
collectionId Integer 12345 The unique identifier for the collection.

Status 200 application/json

Object type: Collection

Download schema: keyCollectionDto-schema.json

Response body:

{
    "id": 108051,
    "name": "Bookstore Access",
    "description": "A collection with API keys for use by the Bookstore API standard users.",
    "keyCount": 21,
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "dirty": false,
    "grantedACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "dirtyACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "quota": {
        "enabled": true,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}

  1. If you don’t have a full representation of the object you want to modify, run the List key collections operation.

  2. Select the appropriate collection from the returned array and store its id.

  3. Run the Get a key collection operation for the complete representation of the object.

  4. Modify the Collection object.

  5. PUT the object back to the same URL as the GET: /apikey-manager-api/v1/collections/{collectionId}.

A 200 response confirms success, and the response object reflects your modifications.

Delete a key collection

Deletes a collection and all keys included in the collection.

DELETE /apikey-manager-api/v1/collections/{collectionId}

Sample: /apikey-manager-api/v1/collections/12345

Parameter Type Sample Description
URL path parameters
collectionId Integer 12345 The unique identifier for the collection.

Status 204

  1. If you don’t already have an id value, run the List key collections operation.

  2. Select the appropriate collection from the returned array and store its id.

  3. Make a DELETE request to /apikey-manager-api/v1/collections/{collectionId}.

A 204 response confirms the object has been deleted.

List collection endpoints

Returns information about all endpoints assigned to the contract and group under which you created the collection. The format of the response data for this operation is managed by the API Endpoints API.

GET /apikey-manager-api/v1/collections/{collectionId}/endpoints

Sample: /apikey-manager-api/v1/collections/12345/endpoints

Parameter Type Sample Description
URL path parameters
collectionId Integer 12345 The unique identifier for the collection.

Status 200 application/json

Object type: Collection

Download schema: apiEndpointDto-schema.json

Response body:

[
    {
        "createdBy": null,
        "createDate": null,
        "updateDate": null,
        "updatedBy": null,
        "apiEndPointId": 418250,
        "apiEndPointName": "Bookstore API",
        "description": null,
        "basePath": "/bookstore",
        "consumeType": null,
        "apiEndPointScheme": null,
        "apiEndPointVersion": null,
        "contractId": null,
        "groupId": null,
        "versionNumber": 2,
        "clonedFromVersion": null,
        "apiEndPointLocked": null,
        "protectedByApiKey": true,
        "source": null,
        "positiveConstrainsEnabled": null,
        "availableActions": null,
        "graphQL": null,
        "lockVersion": -1,
        "caseSensitive": true,
        "isGraphQL": null,
        "apiEndPointHosts": [],
        "apiCategoryIds": [],
        "stagingVersion": {
            "versionNumber": 1,
            "status": "ACTIVE",
            "timestamp": "2019-02-14T19:11:18.000+0000",
            "lastError": null
        },
        "productionVersion": {
            "versionNumber": 2,
            "status": "ACTIVE",
            "timestamp": "2019-02-14T19:19:25.000+0000",
            "lastError": null
        },
        "apiResourceBaseInfo": [
            {
                "createdBy": null,
                "createDate": null,
                "updateDate": null,
                "updatedBy": null,
                "apiResourceId": 2681616,
                "apiResourceName": "book",
                "resourcePath": "/book",
                "description": null,
                "link": null,
                "apiResourceClonedFromId": 79791,
                "apiResourceLogicId": 79491,
                "private": true,
                "lockVersion": -1,
                "stagingVersion": {
                    "versionNumber": 1,
                    "status": "ACTIVE",
                    "timestamp": "2019-02-14T19:11:18.000+0000",
                    "lastError": null
                },
                "productionVersion": {
                    "versionNumber": 2,
                    "status": "ACTIVE",
                    "timestamp": "2019-02-14T19:19:25.000+0000",
                    "lastError": null
                },
                "methods": [
                    {
                        "apiResourceMethodId": 185341,
                        "apiResourceMethodLogicId": 106349,
                        "apiResourceMethod": "GET"
                    },
                    {
                        "apiResourceMethodId": 126342,
                        "apiResourceMethodLogicId": 106150,
                        "apiResourceMethod": "POST"
                    }
                ]
            }
        ]
    }
]

  1. If you don’t already have an id value of the appropriate Collection object run the List key collections operation.

  2. Make a GET request to /apikey-manager-api/v1/collections/{collectionId}/endpoints.

The response is an array of Endpoint objects.

Edit an ACL

Updates the access control list of a collection by adding or removing endpoint, resource, and HTTP method information from the ACL.

PUT /apikey-manager-api/v1/collections/{collectionId}/acl

Sample: /apikey-manager-api/v1/collections/12345/acl

Content-Type: application/json

Object type: Collection

Download schema: aclList-schema.json

Request body:

[
    "ENDPOINT-183165",
    "ENDPOINT-200159",
    "RESOURCE-9218",
    "METHOD-124320",
    "METHOD-124321"
]
Parameter Type Sample Description
URL path parameters
collectionId Integer 12345 The unique identifier for the collection.

Status 200 application/json

Object type: Collection

Download schema: keyCollectionDto-schema.json

Response body:

{
    "id": 108051,
    "name": "Bookstore Access",
    "description": "A collection with API keys for use by the Bookstore API standard users.",
    "keyCount": 21,
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "dirty": false,
    "grantedACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "dirtyACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "quota": {
        "enabled": true,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}

  1. Run the List collection endpoints operation.

  2. If you want to add an endpoint to an ACL, pick the appropriate endpoint from the apiEndPoints array and store its apiEndpointId.

  3. If you want to add a resource to an ACL, pick the appropriate resource from the apiResourceBaseInfo array and store its apiResourceLogicId.

  4. If you want to add a method to an ACL, pick the appropriate method from the methods array and store its apiResourceMethodLogicId.

  5. Build an array of the endpoint, resource, and method items that you want to add to an ACL. Prefix their apiEndpointId, apiResourceLogicId, or apiResourceMethodLogicId values with the ENDPOINT-, RESOURCE-, or METHOD- string. For example, ENDPOINT-1234. Note: If you add an ENDPOINT, RESOURCE, or METHOD without explicitly specifying its child or parent items, the API adds all its child and any parent items. For example, by adding only RESOURCE_1234, you also add all child methods and the parent endpoint this resource is associated with.

  6. If you don’t already have an id value of the appropriate Collection object, run the List key collections operation.

  7. Select the appropriate collection from the returned array and store its id.

  8. PUT the array to /apikey-manager-api/v1/collections/{collectionId}/acl

A 200 response confirms success, and the response object reflects your modifications.

Edit quota settings

Updates the quota settings in a collection.

PUT /apikey-manager-api/v1/collections/{collectionId}/quota

Sample: /apikey-manager-api/v1/collections/12345/quota

Content-Type: application/json

Object type: Quota

Download schema: quotaCommand-schema.json

Request body:

{
    "enabled": true,
    "value": 177,
    "interval": "HOUR_1",
    "headers": {
        "denyLimitHeaderShown": true,
        "denyRemainingHeaderShown": true,
        "denyNextHeaderShown": true,
        "allowLimitHeaderShown": true,
        "allowRemainingHeaderShown": true,
        "allowResetHeaderShown": true
    }
}
Parameter Type Sample Description
URL path parameters
collectionId Integer 12345 The unique identifier for the collection.

Status 200 application/json

Object type: Collection

Download schema: keyCollectionDto-schema.json

Response body:

{
    "id": 108051,
    "name": "Bookstore Access",
    "description": "A collection with API keys for use by the Bookstore API standard users.",
    "keyCount": 21,
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "dirty": false,
    "grantedACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "dirtyACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "quota": {
        "enabled": true,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}

  1. If you don’t already have an id value of the appropriate Collection object, run the List key collections operation.

  2. Select the appropriate collection from the returned array and store its id.

  3. Build the Quota object by specifying its enabled, value, and interval values.

  4. Make a PUT request to /apikey-manager-api/v1/collections/{collectionId}/quota

A 200 response confirms success, and the response object reflects your modifications.

List keys

Returns keys included in a collection based on the specified criteria.

GET /apikey-manager-api/v1/keys{?collectionId,filter,pageNumber,keyType,pageSize,sortDirection,sortColumn}

Sample: /apikey-manager-api/v1/keys?collectionId=12345&filter=test&pageNumber=3&keyType=Active&pageSize=25&sortDirection=asc&sortColumn=id

Parameter Type Sample Description
Optional query parameters
collectionId Integer 12345 The unique identifier for the collection that includes the keys.
filter String test The search phrase to filter the keys by. The phrase can be a part of the description, tags, or label.
keyType Enumeration Active The type of keys to return, either All for all keys in the collection, Active for keys that can be used to access resources and endpoints associated with the collection, Revoked for keys that cannot be used to access resources and endpoints associated with the collection, or Pending for keys with changes that are being propagated to the Akamai network.
pageNumber Integer 3 The page number index.
pageSize Integer 25 The number of keys on each page of results.
sortColumn Enumeration id The name of the column to sort the keys by. The keys can be sorted by their unique id, label, or description.
sortDirection Enumeration asc The order to sort the keys in, either asc for ascending or desc for descending.

Status 200 application/json

Object type: Key

Download schema: keyPage-schema.json

Response body:

{
    "filter": "external",
    "pageNumber": 1,
    "pageSize": 2,
    "sortColumn": "id",
    "sortDirection": "desc",
    "totalItems": 100,
    "items": [
        {
            "id": 403041,
            "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
            "label": "external",
            "collectionName": "Bookstore Access",
            "collectionId": 108051,
            "description": "A key for external bookstore users.",
            "revoked": false,
            "dirty": true,
            "createdAt": "2019-05-30T10:36:33.265221Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": -1,
            "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
            "quotaUpdateState": "PROCESSING",
            "tags": [
                "standard",
                "external"
            ]
        },
        {
            "id": 403040,
            "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
            "label": "external",
            "collectionName": "Bookstore Access",
            "collectionId": 108051,
            "description": "A key for external bookstore users.",
            "revoked": false,
            "dirty": true,
            "createdAt": "2019-05-30T10:36:33.265221Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": -1,
            "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
            "quotaUpdateState": "PROCESSING",
            "tags": [
                "standard",
                "external"
            ]
        }
    ]
}

  1. Optionally set the collectionId query parameter to list keys included in a specific collection.

  2. Optionally set the filter query parameter to list keys that contain a specific phrase as part of their description, tags, or label.

  3. If you want to modify pagination, set the pageSize query parameter for the number of records per page, and the pageNumber.

  4. If you want to affect how the output is sorted, set the sortDirection query parameter to either asc or desc and the sortColumn query parameter to id, label, or description.

  5. If you want to list keys of a specific type, set the keyType query parameter to All, Active, Revoked, or Pending.

  6. Make a GET request to /apikey-manager-api/v1/keys{?collectionId,filter,pageNumber,keyType,pageSize,sortDirection,sortColumn}.

The response includes an array of Key objects.

Create keys

Creates a collection of keys with unassigned values. To generate keys with assigned values, use the Generate keys operation.

POST /apikey-manager-api/v1/keys

Content-Type: application/json

Object type: CreateKey

Download schema: createNewKeyCommand-schema.json

Request body:

{
    "collectionId": 108051,
    "value": "87e2a500-649b-49d6-98be-cf278c5ebbb5",
    "label": "standard",
    "description": "A key for standard user access.",
    "tags": [
        "external"
    ]
}

Status 201 application/json

Headers:

Location: /apikey-manager-api/v1/keys/705050

Object type: Key

Download schema: keyDto-schema.json

Response body:

{
    "id": 403040,
    "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
    "label": "external",
    "collectionName": "Bookstore Access",
    "collectionId": 108051,
    "description": "A key for external bookstore users.",
    "revoked": false,
    "dirty": true,
    "createdAt": "2019-05-30T10:36:33.265221Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": -1,
    "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
    "quotaUpdateState": "PROCESSING",
    "tags": [
        "standard",
        "external"
    ]
}

  1. If you don’t already have an id value of the appropriate Collection object, run the List key collections operation.

  2. Select the appropriate collection from the returned array and store its id.

  3. Build a CreateKey object by providing its value and collectionId values.

  4. Optionally you can add new or existing tags to the object. Run the List tags operation for a list of existing tags.

  5. POST the object to /apikey-manager-api/v1/keys.

The response reflects back the complete Key object. You can access the newly created key at the URL specified in the location response header.

Get a key

Returns information about a key.

GET /apikey-manager-api/v1/keys/{keyId}

Sample: /apikey-manager-api/v1/keys/54321

Parameter Type Sample Description
URL path parameters
keyId Integer 54321 The unique identifier for the key.

Status 200 application/json

Object type: Key

Download schema: keyDto-schema.json

Response body:

{
    "id": 403040,
    "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
    "label": "external",
    "collectionName": "Bookstore Access",
    "collectionId": 108051,
    "description": "A key for external bookstore users.",
    "revoked": false,
    "dirty": true,
    "createdAt": "2019-05-30T10:36:33.265221Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": -1,
    "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
    "quotaUpdateState": "PROCESSING",
    "tags": [
        "standard",
        "external"
    ]
}

  1. If you don’t already have an id value of the appropriate Key object, run the List keys operation.

  2. Select the appropriate key from the returned array and store its id.

  3. Make a GET request to /apikey-manager-api/v1/keys/{keyId}.

The response is a Key object.

Edit a key

Updates information about a key.

PUT /apikey-manager-api/v1/keys/{keyId}

Sample: /apikey-manager-api/v1/keys/54321

Content-Type: application/json

Object type: Key

Download schema: keyDto-schema.json

Request body:

{
    "id": 403040,
    "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
    "label": "external",
    "collectionName": "Bookstore Access",
    "collectionId": 108051,
    "description": "A key for external bookstore users.",
    "revoked": false,
    "dirty": true,
    "createdAt": "2019-05-30T10:36:33.265221Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": -1,
    "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
    "quotaUpdateState": "PROCESSING",
    "tags": [
        "standard",
        "external"
    ]
}
Parameter Type Sample Description
URL path parameters
keyId Integer 54321 The unique identifier for the key.

Status 200 application/json

Object type: Key

Download schema: keyDto-schema.json

Response body:

{
    "id": 403040,
    "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
    "label": "external",
    "collectionName": "Bookstore Access",
    "collectionId": 108051,
    "description": "A key for external bookstore users.",
    "revoked": false,
    "dirty": true,
    "createdAt": "2019-05-30T10:36:33.265221Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": -1,
    "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
    "quotaUpdateState": "PROCESSING",
    "tags": [
        "standard",
        "external"
    ]
}

  1. If you don’t have a full representation of the object you want to modify, run the List keys operation.

  2. Select the appropriate key from the returned array and store its id.

  3. Run the Get a key operation for the complete representation of the object.

  4. Modify the Key object.

  5. PUT the object back to the same URL as the GET: /apikey-manager-api/v1/keys/{keyId}.

A 200 response confirms success, and the response object reflects your modifications.

Import keys

Imports keys from a CSV, XML, or JSON file to a collection. When making a request to import keys, embed the data structure that defines the contents of the import file in a JSON object. For details, see Import keys in different formats.

POST /apikey-manager-api/v1/keys/import

Content-Type: application/json

Object type: ImportKeys

Download schema: importKeysCommand-schema.json

Request body:

{
    "name": "import.json",
    "content": "[{\"value\":\"cf527010-63e8-45ae-91e2-29757180631e\",\"label\":\"premium\",\"tags\":[\"external\",\"premium\"]},{\"value\":\"cf557010-63e8-45fg-94e2-29757180631e\",\"label\":\"premium\",\"external\":[\"premium\",\"temp\"]}]",
    "size": 271,
    "collectionId": 58002
}

Status 204

Import keys in different formats

Follow these steps to build the JSON request object:

  1. If you don’t already have an id value of the appropriate Collection object, run the List key collections operation.

  2. Select the appropriate collection from the returned array and store its id.

  3. Build an ImportKeys object by providing its collectionId, name, and size values.

  4. Serialize the data for the keys to import in JSON, XML, or CSV format as shown in this example. Encode the data within the request object’s content string.

  5. POST the object to /apikey-manager-api/v1/keys/import.

A 204 response confirms that the import operation was successful.

Encoding JSON key data

Structure the API key JSON data such as this example:

[
  {
    "value": "cf527010-63e8-45ae-91e2-29757180631e",
    "label": "premium",
    "tags": [
      "external",
      "premium"
    ]
  },
  {
    "value": "cf557010-63e8-45fg-94e2-29757180631e",
    "label": "premium",
    "tags": [
      "premium",
      "temp"
    ]
  }
]

In the JSON request object, escape all quotation marks with a backslash. Optionally, remove all whitespaces or use the \n character sequences to denote newlines.

{
    "name": "import.json",
    "content": "[{\"value\":\"cf527010-63e8-45ae-91e2-29757180631e\",\"label\":\"premium\",\"tags\":[\"external\",\"premium\"]},{\"value\":\"cf557010-63e8-45fg-94e2-29757180631e\",\"label\":\"premium\",\"tags\":[\"premium\",\"temp\"]}]",
    "size": 653,
    "collectionId": 58002
}

Encoding XML key data

Structure the API key XML data. If you assign more than one tag value to a key, use a semicolon to delimit the values such as this example:

<?xml version="1.0"?>
<keys>
   <key>
      <value>cf527010-63e8-45ae-91e2-29757180631e</value>
      <label>premium</label>
      <tags>external;premium</tags>
   </key>
</keys>

In the JSON request object, escape all quotation marks with a backslash. Optionally, remove all whitespaces between XML tags or use the \n character sequences to denote newlines.

{
    "name": "import.xml",
    "content":"<?xml version=\"1.0\"?><keys><key><value>cf527010-63e8-45ae-91e2-29757180631e</value><label>premium</label><tags>external;premium</tags></key></keys>",
    "size": 544,
    "collectionId": 58002
}

Encoding CSV key data

Structure the API key CSV data. If you assign more than one tag value to a key, use a semicolon to delimit the values. Make sure the fields VALUE, LABEL, and TAGS follow the order as in this example:

VALUE,LABEL,TAGS
cf527010-63e8-45ae-91e2-29757180631e,premium,external;premium
f557010-63e8-45fg-94e2-29757180631e,premium,premium;temp

In the JSON request object, use the newline character sequence (\n) to denote each newline in the CSV file.

{
    "name": "import.csv",
    "content": "VALUE,LABEL,TAGS\ncf527010-63e8-45ae-91e2-29757180631e,premium,external;premium\ncf557010-63e8-45fg-94e2-29757180631e,premium,premium;temp",
    "size": 466,
    "collectionId": 58002
}

Generate keys

Creates a collection of keys with assigned values. To create keys and assign your own values, use the Create keys operation.

POST /apikey-manager-api/v1/keys/generate

Content-Type: application/json

Object type: GenerateKeys

Download schema: generateKeysCommand-schema.json

Request body:

{
    "collectionId": 108051,
    "count": 20,
    "incrementLabel": false,
    "label": "temporary",
    "description": "A temporary key for trial users.",
    "tags": [
        "temp",
        "external"
    ]
}

Status 204

  1. If you don’t already have an id value of the appropriate Collection object, run the List key collections operation.

  2. Select the appropriate collection from the returned array and store its id.

  3. Build a GenerateKeys object by providing its collectionId and count values.

  4. Optionally you can add new or existing tags to the object. Run the List tags operation for a list of existing tags.

  5. POST the object to /apikey-manager-api/v1/keys/generate.

A 204 response confirms that the operation was successful.

Move keys

Moves keys from one collection to another. For details, see move keys to a new collection or move keys to an existing collection.

POST /apikey-manager-api/v1/keys/move

Content-Type: application/json

Object type: MoveKeys

Download schema: moveKeysCommand-schema.json

Request body:

{
    "collectionId": 108052,
    "keys": [
        404001,
        403048
    ]
}

Status 204

Move keys to an existing collection

This section shows you how to move API keys from a key collection to an already existing collection. Alternatively, you can move keys to a new collection.

A request body to move keys might look like this:

{
    "collectionId": 108052,
    "keys": [
        404001,
        403048
    ]
}

Use these steps to build the JSON object:

  1. If you don’t already have the id values of the appropriate Key objects, run the List keys operation.

  2. Select the appropriate keys from the returned array and store their id values.

  3. Run the List key collections operation.

  4. Select the appropriate collection from the returned array and store its id value as collectionId.

  5. Build a MoveKeys object by specifying the collectionId value.

  6. POST the object to /apikey-manager-api/v1/keys/move.

A 204 response confirms that the move operation was successful.

Move keys to a new collection

This section shows you how to move API keys from a key collection to a new collection. Alternatively, you can move keys to an existing collection.

A request body for this method of moving keys might look like this:

{
    "newCollectionName": "Bookstore Trial",
    "newCollectionDescription": "A collection with API keys for trial Bookstore users.",
    "newCollectionContractId": "M-297UAQ5",
    "newCollectionGroupId": 110202,
    "keys": [
        404001,
        403048
    ]
}

Follow these steps to build the JSON object:

  1. If you don’t already have the id values of the appropriate Key objects, run the List keys operation.

  2. Select the appropriate keys from the returned array and store their id values.

  3. If you don’t already have contractId and groupId values, run the List contracts and groups operation in the API Endpoint Definition API.

  4. From the response array, choose the appropriate pairing of contract and group, and store its contractId and groupId values as newCollectionContractId, and newCollectionGroupId.

  5. Build a MoveKeys object by specifying the newCollectionName, newCollectionContractId, and newCollectionGroupId values, and optionally the newCollectionDescription value.

  6. POST the object to /apikey-manager-api/v1/keys/move.

A 204 response confirms that the move operation was successful.

Revoke keys

Revokes keys in a collection and marks them as revoked. The revoked keys can be restored within the next 120 days and after this period they’re deleted.

POST /apikey-manager-api/v1/keys/revoke

Content-Type: application/json

Object type: RevokeRestoreKeys

Download schema: revokeKeysCommand-schema.json

Request body:

{
    "keys": [
        89011,
        89012,
        89013
    ]
}

Status 204

  1. If you don’t already have the id values of the appropriate Key objects, run the List keys operation.

  2. Select the appropriate keys from the returned array and store their id values.

  3. Build a RevokeRestoreKeys object by including all id values of the keys that you want to revoke in an array.

  4. POST the object to /apikey-manager-api/v1/keys/revoke.

A 204 response confirms that the import operation was successful.

Restore revoked keys

Restores previously revoked keys in a collection. This operation is only available in the 120 days following the revocation.

POST /apikey-manager-api/v1/keys/restore

Content-Type: application/json

Object type: RevokeRestoreKeys

Download schema: revokeKeysCommand-schema.json

Request body:

{
    "keys": [
        89011,
        89012,
        89013
    ]
}

Status 204

  1. If you don’t already have an id value of the appropriate Key object, run the List keys operation and set the keyType query parameter to Revoked.

  2. Select the appropriate keys from the returned array and store their id values.

  3. Build a RevokeRestoreKeys object by including all id values of the keys that you want to restore in an array.

  4. POST the object to /apikey-manager-api/v1/keys/restore.

A 204 response confirms that the import operation was successful.

Reset key quota

Resets the quota limit for selected keys.

POST /apikey-manager-api/v1/keys/quota-reset

Content-Type: application/json

Object type: Key

Download schema: keysList-schema.json

Request body:

{
    "keys": [
        "1324149",
        "1324150",
        "1324151"
    ]
}

Status 204

  1. If you don’t already have the id values of the appropriate Key objects, run the List keys operation.

  2. Select the appropriate keys from the returned array and store their id values.

  3. Build an array of id values of all keys that you want to reset quota for.

  4. POST the object to /apikey-manager-api/v1/keys/quota-reset.

A 204 response confirms that the import operation was successful.

List tags

Returns all existing tags. You can add new tags during the key creation. See either the Create keys or Generate keys operation.

GET /apikey-manager-api/v1/tags

Status 200 application/json

Object type: Key

Download schema: tagsList-schema.json

Response body:

[
    "external",
    "standard",
    "temp",
    "premium"
]

Generate a report

Creates a report in a JSON format for a specific version of a report. You can specify the start and end date for the report data and the aggregation interval for each record.

POST /apikey-manager-api/v1/reports/{reportName}/versions/{reportVersion}/report-data{?start,end,interval}

Sample: /apikey-manager-api/v1/reports/rapidkey-by-quota/versions/1/report-data?start=2016-07-01T00%3A00%3A00Z&end=2016-07-02T00%3A00%3A00Z&interval=DAY

Content-Type: application/json

Object type: Query

Download schema: report-request-schema.json

Request body:

{
    "filters": {
        "api_key": [
            "403040"
        ]
    }
}
Parameter Type Sample Description
URL path parameters
reportName Enumeration rapidkey-by-quota The type of report that you want to generate. Either rapidkey-by-quota or rapidkey-by-time.
reportVersion Integer 1 The version of a report.
Required query parameters
end String 2016-07-02T00:00:00Z Indicates the end date for the report data, in ISO 8601 format. Any data that matches the end value’s timestamp is excluded from the rapidkey-by-time report. The rapidkey-by-quota report displays data only for the date indicated by this timestamp.
interval Enumeration DAY The duration of each data record, either FIVE_MINUTES, HOUR, DAY, WEEK, or MONTH. The support for specific interval values may vary depending on the report type.
start String 2016-07-01T00:00:00Z Indicates the start date for the report, in ISO 8601 format.

Status 200 application/json

Object type: Report

Download schema: report-response-schema.json

Response body:

{
    "metadata": {
        "name": "rapidkey-by-quota",
        "version": "1",
        "interval": "FIVE_MINUTES",
        "start": "2018-05-16T00:00:00Z",
        "end": "2018-05-18T00:00:00Z",
        "availableDataEnds": "2018-05-17T09:00:50.771902Z",
        "suggestedRetryTime": null,
        "rowCount": 17,
        "objectType": "rapidfile",
        "groupBy": [
            "api_key"
        ],
        "objectIds": [
            "ymdfile"
        ],
        "filters": [
            {
                "name": "api_key",
                "values": [
                    "219002",
                    "245001"
                ]
            }
        ],
        "columns": [
            {
                "name": "groupBy",
                "label": "api_key"
            },
            {
                "name": "quotaUsage",
                "label": "Quota Used"
            }
        ]
    },
    "summaryStatistics": {},
    "data": [
        {
            "api_key": " (244253)",
            "apikeyCollection": "100/hour",
            "time_interval": "0",
            "quotaUsage": "0"
        },
        {
            "api_key": " (244250)",
            "apikeyCollection": "100/twelve hours",
            "time_interval": "2",
            "quotaUsage": "0"
        },
        {
            "api_key": " (224173)",
            "apikeyCollection": "1000/month",
            "time_interval": "5",
            "quotaUsage": "0"
        }
    ]
}

List throttling counters

Returns all existing throttling counters available for the current contract and group.

GET /apikey-manager-api/v1/counters

Status 200 application/json

Object type: ThrottlingCounter

Download schema: counterList-schema.json

Response body:

[
    {
        "id": 61,
        "enabled": true,
        "name": "Books counter",
        "description": "A counter for requests to the books resource within the Bookstore API.",
        "groupId": 105425,
        "throttling": 1000,
        "onOverLimit": "WARN",
        "contractId": "F-IGRAJY",
        "status": "ACTIVE",
        "createdAt": "2019-02-05T08:31:32.659081Z",
        "updatedAt": "2019-02-15T20:12:01.197694Z",
        "createdBy": "bookstore_admin",
        "updatedBy": "bookstore_admin",
        "dirty": false,
        "errorResponse": {
            "overrideDefaults": true,
            "statusCode": 429,
            "body": null,
            "headers": []
        },
        "headers": {
            "sendLimitToClient": false,
            "sendLimitToOrigin": false,
            "sendRateToClient": false,
            "sendRateToOrigin": true
        },
        "rules": [
            {
                "id": 64,
                "type": "ACL_ENTRY",
                "values": [
                    "ENDPOINT-290100",
                    "RESOURCE-9946",
                    "METHOD-43226",
                    "METHOD-43227"
                ]
            },
            {
                "id": 61,
                "type": "KEY",
                "values": [
                    316013,
                    314095,
                    314097,
                    314098
                ]
            },
            {
                "id": 62,
                "type": "KEY_COLLECTION",
                "values": [
                    416013,
                    414095,
                    414097,
                    414098
                ]
            }
        ]
    }
]

Create a throttling counter

Creates a new throttling counter under the selected contract and group.

POST /apikey-manager-api/v1/counters

Content-Type: application/json

Object type: ThrottlingCounter

Download schema: counter-schema.json

Request body:

{
    "id": 61,
    "enabled": true,
    "name": "Books counter",
    "description": "A counter for requests to the books resource within the Bookstore API.",
    "groupId": 105425,
    "throttling": 1000,
    "onOverLimit": "WARN",
    "contractId": "F-IGRAJY",
    "status": "ACTIVE",
    "createdAt": "2019-02-05T08:31:32.659081Z",
    "updatedAt": "2019-02-15T20:12:01.197694Z",
    "createdBy": "bookstore_admin",
    "updatedBy": "bookstore_admin",
    "dirty": false,
    "errorResponse": {
        "overrideDefaults": true,
        "statusCode": 429,
        "body": null,
        "headers": []
    },
    "headers": {
        "sendLimitToClient": false,
        "sendLimitToOrigin": false,
        "sendRateToClient": false,
        "sendRateToOrigin": true
    },
    "rules": [
        {
            "id": 64,
            "type": "ACL_ENTRY",
            "values": [
                "ENDPOINT-290100",
                "RESOURCE-9946",
                "METHOD-43226",
                "METHOD-43227"
            ]
        },
        {
            "id": 61,
            "type": "KEY",
            "values": [
                316013,
                314095,
                314097,
                314098
            ]
        },
        {
            "id": 62,
            "type": "KEY_COLLECTION",
            "values": [
                416013,
                414095,
                414097,
                414098
            ]
        }
    ]
}

Status 201 application/json

Headers:

Location: /apikey-manager-api/v1/counters/101

Object type: ThrottlingCounter

Download schema: counter-schema.json

Response body:

{
    "id": 61,
    "enabled": true,
    "name": "Books counter",
    "description": "A counter for requests to the books resource within the Bookstore API.",
    "groupId": 105425,
    "throttling": 1000,
    "onOverLimit": "WARN",
    "contractId": "F-IGRAJY",
    "status": "ACTIVE",
    "createdAt": "2019-02-05T08:31:32.659081Z",
    "updatedAt": "2019-02-15T20:12:01.197694Z",
    "createdBy": "bookstore_admin",
    "updatedBy": "bookstore_admin",
    "dirty": false,
    "errorResponse": {
        "overrideDefaults": true,
        "statusCode": 429,
        "body": null,
        "headers": []
    },
    "headers": {
        "sendLimitToClient": false,
        "sendLimitToOrigin": false,
        "sendRateToClient": false,
        "sendRateToOrigin": true
    },
    "rules": [
        {
            "id": 64,
            "type": "ACL_ENTRY",
            "values": [
                "ENDPOINT-290100",
                "RESOURCE-9946",
                "METHOD-43226",
                "METHOD-43227"
            ]
        },
        {
            "id": 61,
            "type": "KEY",
            "values": [
                316013,
                314095,
                314097,
                314098
            ]
        },
        {
            "id": 62,
            "type": "KEY_COLLECTION",
            "values": [
                416013,
                414095,
                414097,
                414098
            ]
        }
    ]
}

  1. Build a ThrottlingCounter object by specifying the unique name, contractId and groupId values, the allowed throttling limit, whether the counter should be enabled, and the behavior of edge servers onOverLimit.

  2. POST the object to /apikey-manager-api/v1/counters.

The operation responds with a ThrottlingCounter object.

Get a throttling counter

Returns information about a throttling counter.

GET /apikey-manager-api/v1/counters/{counterId}

Sample: /apikey-manager-api/v1/counters/54321

Parameter Type Sample Description
URL path parameters
counterId Integer 54321 The unique identifier for the throttling counter.

Status 200 application/json

Object type: ThrottlingCounter

Download schema: counter-schema.json

Response body:

{
    "id": 61,
    "enabled": true,
    "name": "Books counter",
    "description": "A counter for requests to the books resource within the Bookstore API.",
    "groupId": 105425,
    "throttling": 1000,
    "onOverLimit": "WARN",
    "contractId": "F-IGRAJY",
    "status": "ACTIVE",
    "createdAt": "2019-02-05T08:31:32.659081Z",
    "updatedAt": "2019-02-15T20:12:01.197694Z",
    "createdBy": "bookstore_admin",
    "updatedBy": "bookstore_admin",
    "dirty": false,
    "errorResponse": {
        "overrideDefaults": true,
        "statusCode": 429,
        "body": null,
        "headers": []
    },
    "headers": {
        "sendLimitToClient": false,
        "sendLimitToOrigin": false,
        "sendRateToClient": false,
        "sendRateToOrigin": true
    },
    "rules": [
        {
            "id": 64,
            "type": "ACL_ENTRY",
            "values": [
                "ENDPOINT-290100",
                "RESOURCE-9946",
                "METHOD-43226",
                "METHOD-43227"
            ]
        },
        {
            "id": 61,
            "type": "KEY",
            "values": [
                316013,
                314095,
                314097,
                314098
            ]
        },
        {
            "id": 62,
            "type": "KEY_COLLECTION",
            "values": [
                416013,
                414095,
                414097,
                414098
            ]
        }
    ]
}

  1. If you don’t already have a counterId value, run the List throttling counters operation.

  2. Select the appropriate throttling counter from the returned array and store its counterId.

  3. Make a GET request to /apikey-manager-api/v1/counters/{counterId}.

The response is a ThrottlingCounter object.

Edit a throttling counter

Updates information about a throttling counter.

PUT /apikey-manager-api/v1/counters/{counterId}

Sample: /apikey-manager-api/v1/counters/54321

Content-Type: application/json

Object type: ThrottlingCounter

Download schema: counter-schema.json

Request body:

{
    "id": 61,
    "enabled": true,
    "name": "Books counter",
    "description": "A counter for requests to the books resource within the Bookstore API.",
    "groupId": 105425,
    "throttling": 1000,
    "onOverLimit": "WARN",
    "contractId": "F-IGRAJY",
    "status": "ACTIVE",
    "createdAt": "2019-02-05T08:31:32.659081Z",
    "updatedAt": "2019-02-15T20:12:01.197694Z",
    "createdBy": "bookstore_admin",
    "updatedBy": "bookstore_admin",
    "dirty": false,
    "errorResponse": {
        "overrideDefaults": true,
        "statusCode": 429,
        "body": null,
        "headers": []
    },
    "headers": {
        "sendLimitToClient": false,
        "sendLimitToOrigin": false,
        "sendRateToClient": false,
        "sendRateToOrigin": true
    },
    "rules": [
        {
            "id": 64,
            "type": "ACL_ENTRY",
            "values": [
                "ENDPOINT-290100",
                "RESOURCE-9946",
                "METHOD-43226",
                "METHOD-43227"
            ]
        },
        {
            "id": 61,
            "type": "KEY",
            "values": [
                316013,
                314095,
                314097,
                314098
            ]
        },
        {
            "id": 62,
            "type": "KEY_COLLECTION",
            "values": [
                416013,
                414095,
                414097,
                414098
            ]
        }
    ]
}
Parameter Type Sample Description
URL path parameters
counterId Integer 54321 The unique identifier for the throttling counter.

Status 200 application/json

Object type: ThrottlingCounter

Download schema: counter-schema.json

Response body:

{
    "id": 61,
    "enabled": true,
    "name": "Books counter",
    "description": "A counter for requests to the books resource within the Bookstore API.",
    "groupId": 105425,
    "throttling": 1000,
    "onOverLimit": "WARN",
    "contractId": "F-IGRAJY",
    "status": "ACTIVE",
    "createdAt": "2019-02-05T08:31:32.659081Z",
    "updatedAt": "2019-02-15T20:12:01.197694Z",
    "createdBy": "bookstore_admin",
    "updatedBy": "bookstore_admin",
    "dirty": false,
    "errorResponse": {
        "overrideDefaults": true,
        "statusCode": 429,
        "body": null,
        "headers": []
    },
    "headers": {
        "sendLimitToClient": false,
        "sendLimitToOrigin": false,
        "sendRateToClient": false,
        "sendRateToOrigin": true
    },
    "rules": [
        {
            "id": 64,
            "type": "ACL_ENTRY",
            "values": [
                "ENDPOINT-290100",
                "RESOURCE-9946",
                "METHOD-43226",
                "METHOD-43227"
            ]
        },
        {
            "id": 61,
            "type": "KEY",
            "values": [
                316013,
                314095,
                314097,
                314098
            ]
        },
        {
            "id": 62,
            "type": "KEY_COLLECTION",
            "values": [
                416013,
                414095,
                414097,
                414098
            ]
        }
    ]
}

  1. If you don’t already have a counterId value, run the List throttling counters operation.

  2. Select the appropriate throttling counter from the returned array and store its counterId.

  3. Run the Get a throttling counter operation for the complete representation of the object.

  4. Modify the ThrottlingCounter object.

  5. PUT the object to /apikey-manager-api/v1/counters/{counterId}.

A 200 response confirms success, and the response object reflects your modifications.

Delete a throttling counter

Removes a throttling counter.

DELETE /apikey-manager-api/v1/counters/{counterId}

Sample: /apikey-manager-api/v1/counters/54321

Parameter Type Sample Description
URL path parameters
counterId Integer 54321 The unique identifier for the throttling counter.

Status 204

  1. If you don’t already have a counterId value, run the List throttling counters operation.

  2. Select the appropriate throttling counter from the returned array and store its counterId.

  3. Make a DELETE request to /apikey-manager-api/v1/counters/{counterId}.

A 204 response confirms the object has been deleted.

List counter endpoints

Returns information about all endpoints assigned to the contract and group under which you created the throttling counter. The format of the response data for this operation is managed by the API Endpoints API. Search the response data for the relevant ACL_ENTRY members (API endpoint IDs, resource IDs, or HTTP methods) to use when running the Create a throttling counter or Update a throttling counter operation.

GET /apikey-manager-api/v1/counters/{counterId}/endpoints

Sample: /apikey-manager-api/v1/counters/54321/endpoints

Parameter Type Sample Description
URL path parameters
counterId Integer 54321 The unique identifier for the throttling counter.

Status 200 application/json

Object type: Collection

Download schema: apiEndpointDto-schema.json

Response body:

[
    {
        "createdBy": null,
        "createDate": null,
        "updateDate": null,
        "updatedBy": null,
        "apiEndPointId": 418250,
        "apiEndPointName": "Bookstore API",
        "description": null,
        "basePath": "/bookstore",
        "consumeType": null,
        "apiEndPointScheme": null,
        "apiEndPointVersion": null,
        "contractId": null,
        "groupId": null,
        "versionNumber": 2,
        "clonedFromVersion": null,
        "apiEndPointLocked": null,
        "protectedByApiKey": true,
        "source": null,
        "positiveConstrainsEnabled": null,
        "availableActions": null,
        "graphQL": null,
        "lockVersion": -1,
        "caseSensitive": true,
        "isGraphQL": null,
        "apiEndPointHosts": [],
        "apiCategoryIds": [],
        "stagingVersion": {
            "versionNumber": 1,
            "status": "ACTIVE",
            "timestamp": "2019-02-14T19:11:18.000+0000",
            "lastError": null
        },
        "productionVersion": {
            "versionNumber": 2,
            "status": "ACTIVE",
            "timestamp": "2019-02-14T19:19:25.000+0000",
            "lastError": null
        },
        "apiResourceBaseInfo": [
            {
                "createdBy": null,
                "createDate": null,
                "updateDate": null,
                "updatedBy": null,
                "apiResourceId": 2681616,
                "apiResourceName": "book",
                "resourcePath": "/book",
                "description": null,
                "link": null,
                "apiResourceClonedFromId": 79791,
                "apiResourceLogicId": 79491,
                "private": true,
                "lockVersion": -1,
                "stagingVersion": {
                    "versionNumber": 1,
                    "status": "ACTIVE",
                    "timestamp": "2019-02-14T19:11:18.000+0000",
                    "lastError": null
                },
                "productionVersion": {
                    "versionNumber": 2,
                    "status": "ACTIVE",
                    "timestamp": "2019-02-14T19:19:25.000+0000",
                    "lastError": null
                },
                "methods": [
                    {
                        "apiResourceMethodId": 185341,
                        "apiResourceMethodLogicId": 106349,
                        "apiResourceMethod": "GET"
                    },
                    {
                        "apiResourceMethodId": 126342,
                        "apiResourceMethodLogicId": 106150,
                        "apiResourceMethod": "POST"
                    }
                ]
            }
        ]
    }
]

  1. If you don’t already have a counterId value, run the List throttling counters operation.

  2. Select the appropriate throttling counter from the returned array and store its counterId.

  3. Make a GET request to /apikey-manager-api/v1/counters/{counterId}/endpoints.

The response includes an array of Endpoint objects.

List counter keys

Returns information about all API keys assigned to the contract and group under which you created the throttling counter. Search the response data for the relevant KEY ID members to use when running the Create a throttling counter or Update a throttling counter operation.

GET /apikey-manager-api/v1/counters/{counterId}/keys

Sample: /apikey-manager-api/v1/counters/54321/keys

Parameter Type Sample Description
URL path parameters
counterId Integer 54321 The unique identifier for the throttling counter.

Status 200 application/json

Object type: Key

Download schema: keyList-schema.json

Response body:

[
    {
        "id": 403040,
        "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
        "label": "external",
        "collectionName": "Bookstore Access",
        "collectionId": 108051,
        "description": "A key for external bookstore users.",
        "revoked": false,
        "dirty": true,
        "createdAt": "2019-05-30T10:36:33.265221Z",
        "revokedAt": null,
        "terminationAt": null,
        "quotaUsage": -1,
        "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
        "quotaUpdateState": "PROCESSING",
        "tags": [
            "standard",
            "external"
        ]
    },
    {
        "id": 403041,
        "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
        "label": "external",
        "collectionName": "Bookstore Access",
        "collectionId": 108051,
        "description": "A key for external bookstore users.",
        "revoked": false,
        "dirty": true,
        "createdAt": "2019-05-30T10:36:33.265221Z",
        "revokedAt": null,
        "terminationAt": null,
        "quotaUsage": -1,
        "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
        "quotaUpdateState": "PROCESSING",
        "tags": [
            "standard",
            "external"
        ]
    }
]

  1. If you don’t already have a counterId value, run the List throttling counters operation.

  2. Select the appropriate throttling counter from the returned array and store its counterId.

  3. Make a GET request to /apikey-manager-api/v1/counters/{counterId}/keys.

The response includes an array of Key objects.

Data

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

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

✓ Member is required in requests, or always present in responses, even if its value is empty or null.
○ Member is optional, and may be omitted in some cases.

Collection

Contains information about a collection.

Download schema: keyCollectionDto-schema.json

Sample GET response:

{
    "id": 108051,
    "name": "Bookstore Access",
    "description": "A collection with API keys for use by the Bookstore API standard users.",
    "keyCount": 21,
    "contractId": "M-297UAQ5",
    "groupId": 110202,
    "dirty": false,
    "grantedACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "dirtyACL": [
        "ENDPOINT-418250",
        "ENDPOINT-447203",
        "METHOD-106349",
        "RESOURCE-79491",
        "METHOD-106350"
    ],
    "quota": {
        "enabled": true,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}

Collection members

Member Type Required Description
Collection: Contains information about a collection.
contractId String ○ The unique identifier for the contract with Akamai under which you deploy the collection.
description String ○ The description that you provide for the collection. If you specify an empty string in the request or omit this member from the object, the JSON response reflects it as null.
dirty Boolean ○ Read-only. Whether the collection contains changes that are being propagated to the Akamai network.
dirtyACL Array ○ Read-only. The endpoints or resources with ACL changes that are being propagated to the Akamai network.
grantedACL Array ○ Read-only. The endpoints, resources, and HTTP methods accessible to API consumers that identify with keys included in the collection.
groupId Integer ✓ The unique identifier for the group in Control Center under which you deploy the collection.
id Integer ○ Read-only. The unique identifier for the collection.
keyCount Integer ○ Read-only. The number of keys included in the collection.
name String ✓ The name of the collection.
quota Collection.quota ○ Read-only. Contains information about quota settings for the collection.
Collection.quota: Contains information about quota settings for the collection.
enabled Boolean ○ Whether you enabled quota settings in the collection.
headers Collection.quota.headers ○ Contains information about the criteria for sending the quota limit response headers.
interval Enumeration ○ The time period for the quota limit in UTC, either HOUR_1 to reset at the start of each hour, HOUR_6 at the start of each sixth hour, HOUR_12 for twice daily, DAY for midnight each day, WEEK for midnight on each Monday, or MONTH for midnight on the first day of each month.
value Integer ○ The number of requests that each key from the collection can send to an API within the specified time period.
Collection.quota.headers: Contains information about the criteria for sending the quota limit response headers.
allowLimitHeaderShown Boolean ○ Whether to send the X-RateLimit-Limit header in a response when the quota remains.
allowRemainingHeaderShown Boolean ○ Whether to send the X-RateLimit-Remaining header in a response when the quota remains.
allowResetHeaderShown Boolean ○ Whether to send the X-RateLimit-Reset header in a response when the quota remains.
denyLimitHeaderShown Boolean ○ Whether to send the X-RateLimit-Limit header in a response when the quota is full.
denyNextHeaderShown Boolean ○ Whether to send the X-RateLimit-Next header in a response when the quota is full.
denyRemainingHeaderShown Boolean ○ Whether to send the X-RateLimit-Remaining header in a response when the quota is full.

Quota

Contains information about quota settings.

Download schema: quotaCommand-schema.json

Sample GET response:

{
    "enabled": true,
    "value": 177,
    "interval": "HOUR_1",
    "headers": {
        "denyLimitHeaderShown": true,
        "denyRemainingHeaderShown": true,
        "denyNextHeaderShown": true,
        "allowLimitHeaderShown": true,
        "allowRemainingHeaderShown": true,
        "allowResetHeaderShown": true
    }
}

Quota members

Member Type Required Description
Quota: Contains information about quota settings.
enabled Boolean ✓ Whether you enabled quota settings in the collection.
headers Quota.headers ○ Contains information about the criteria for sending the quota limit response headers.
interval Enumeration ○ The time period for the quota limit in UTC, either HOUR_1 to reset at the start of each hour, HOUR_6 at the start of each sixth hour, HOUR_12 for twice daily, DAY for midnight each day, WEEK for midnight on each Monday, or MONTH for midnight on the first day of each month.
value Integer ○ The number of requests that each key from the collection can send to an API within the specified time period.
Quota.headers: Contains information about the criteria for sending the quota limit response headers.
allowLimitHeaderShown Boolean ○ Whether to send the X-RateLimit-Limit header in a response when the quota remains.
allowRemainingHeaderShown Boolean ○ Whether to send the X-RateLimit-Remaining header in a response when the quota remains.
allowResetHeaderShown Boolean ○ Whether to send the X-RateLimit-Reset header in a response when the quota remains.
denyLimitHeaderShown Boolean ○ Whether to send the X-RateLimit-Limit header in a response when the quota is full.
denyNextHeaderShown Boolean ○ Whether to send the X-RateLimit-Next header in a response when the quota is full.
denyRemainingHeaderShown Boolean ○ Whether to send the X-RateLimit-Remaining header in a response when the quota is full.

Key

Contains information about a key.

Download schema: keyDto-schema.json

Sample GET response:

{
    "id": 403040,
    "value": "62e6b236-5eab-42c9-8cc1-a71d01536cc0",
    "label": "external",
    "collectionName": "Bookstore Access",
    "collectionId": 108051,
    "description": "A key for external bookstore users.",
    "revoked": false,
    "dirty": true,
    "createdAt": "2019-05-30T10:36:33.265221Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": -1,
    "quotaUsageTimestamp": "1970-01-01T00:00:00Z",
    "quotaUpdateState": "PROCESSING",
    "tags": [
        "standard",
        "external"
    ]
}

Key members

Member Type Required Description
Key: Contains information about a key.
collectionId Integer ○ The unique identifier for the collection that includes the key.
collectionName String ○ Read-only. The name of the collection that includes the key.
createdAt String ○ Read-only. Indicates when the key was created, in ISO 8601 format.
description String ○ The description that you provide for the key.
dirty Boolean ○ Read-only. Whether changes to the key’s status are being propagated to the Akamai network.
id Integer ○ Read-only. The unique identifier for the key.
label String ○ The label that you assign to the key. If you specify an empty string in the request or omit this member from the object, the JSON response reflects it as null.
quotaUpdateState Enumeration ○ Read-only. The key’s quota reset status. Either NONE if no quota reset is in progress, QUEUED if the key is awaiting a quota reset, or PROCESSING if the key’s quota is currently being reset. When the quota resets, the status automatically changes from PROCESSING to NONE.
quotaUsage Integer ○ Read-only. The current quota usage for the key. The value is -1 if the current usage is unknown.
quotaUsageTimestamp String ○ Read-only. Indicates when the key’s quota was updated, in ISO 8601 format.
revoked Boolean ○ Read-only. Whether you revoked the key.
revokedAt String, Null ○ Read-only. Indicates when the key was revoked, in ISO 8601 format.
tags Array ○ The additional categories assigned to the key that you can use as filters.
terminationAt String, Null ○ Read-only. Indicates when the key was deleted, in ISO 8601 format.
value String ○ The value of the key.

CreateKey

Contains information about keys to create with manually assigned values.

Download schema: createNewKeyCommand-schema.json

Sample POST request:

{
    "collectionId": 108051,
    "value": "87e2a500-649b-49d6-98be-cf278c5ebbb5",
    "label": "standard",
    "description": "A key for standard user access.",
    "tags": [
        "external"
    ]
}

CreateKey members

Member Type Required Description
CreateKey: Contains information about keys to create with manually assigned values.
collectionId Integer ✓ The unique identifier for the collection that includes the key.
collectionName String ○ Read-only. The name of the collection that includes the key.
createdAt String ○ Read-only. Indicates when the key was created, in ISO 8601 format.
description String ○ The description that you provide for the key.
dirty Boolean ○ Read-only. Whether changes to the key’s status are being propagated to the Akamai network.
id Integer ○ Read-only. The unique identifier for the key.
incrementLabel Boolean ○ Whether to append an automatic increment to the label of each key. A label’s increment starts with an underscore character followed by a numerical value based on the number of keys that you create. For example, if you create 8 keys, the increments range from _0 to _7. If you create 125 keys, the increments range from _000 to _124.
label String ○ The label that you assign to the key. If you specify an empty string in the request or omit this member from the object, the JSON response reflects it as null.
revoked Boolean ○ Read-only. Whether you revoked the key.
revokedAt String ○ Read-only. Indicates when the key was revoked, in ISO 8601 format.
tags Array ○ The additional categories assigned to the key that you can use as filters.
terminationAt String ○ Read-only. Indicates when the key was deleted, in ISO 8601 format.
value String ✓ The values of the keys. If you want to create more than one key, separate the values by commas, semicolons, or newline sequences ( ).

ImportKeys

Contains information about an import file with details about API keys.

Download schema: importKeysCommand-schema.json

Sample POST request:

{
    "name": "import.json",
    "content": "[{\"value\":\"cf527010-63e8-45ae-91e2-29757180631e\",\"label\":\"premium\",\"tags\":[\"external\",\"premium\"]},{\"value\":\"cf557010-63e8-45fg-94e2-29757180631e\",\"label\":\"premium\",\"external\":[\"premium\",\"temp\"]}]",
    "size": 271,
    "collectionId": 58002
}

ImportKeys members

Member Type Required Description
ImportKeys: Contains information about an import file with details about API keys.
collectionId Integer ✓ The unique identifier for the collection where keys should be imported.
content String ✓ The XML, CSV, or JSON data structure with details about keys to import, encoded within a single string value. See how you can import keys in different formats.
name String ✓ The name of the file with keys to import.
size Integer ✓ The size of the file in bytes.

GenerateKeys

Contains information about keys to generate with automatically assigned values.

Download schema: generateKeysCommand-schema.json

Sample POST request:

{
    "collectionId": 108051,
    "count": 20,
    "incrementLabel": false,
    "label": "temporary",
    "description": "A temporary key for trial users.",
    "tags": [
        "temp",
        "external"
    ]
}

GenerateKeys members

Member Type Required Description
GenerateKeys: Contains information about keys to generate with automatically assigned values.
collectionId Integer ✓ The unique identifier for the collection that includes the key.
collectionName String ○ The name of the collection that includes the key.
count Integer ✓ The number of keys to generate.
createdAt String ○ Read-only. Indicates when the key was created, in ISO 8601 format.
description String ○ The description that you provide for the key.
dirty Boolean ○ Read-only. Whether changes to the key’s status are being propagated to the Akamai network.
id Integer ○ The unique identifier for the key.
incrementLabel Boolean ○ Whether to append an automatic increment to the label of each key. A label’s increment starts with an underscore character followed by a numerical value based on the number of keys that you create. For example, if you create 8 keys, the increments range from _0 to _7. If you create 125 keys, the increments range from _000 to _124.
label String ○ The label that you assign to the key. If you specify an empty string in the request or omit this member from the object, the JSON response reflects it as null.
revoked Boolean ○ Read-only. Whether you revoked the key.
revokedAt String ○ Read-only. Indicates when the key was revoked, in ISO 8601 format.
tags Array ○ The additional categories assigned to the key that you can use as filters.
terminationAt String ○ Read-only. Indicates when the key was deleted, in ISO 8601 format.

MoveKeys

Contains information about keys to move from one collection to another.

Download schema: moveKeysCommand-schema.json

Sample POST request:

{
    "collectionId": 108052,
    "keys": [
        404001,
        403048
    ]
}

MoveKeys members

Member Type Required Description
MoveKeys: Contains information about keys to move from one collection to another.
collectionId Integer ○ The unique identifier for the existing destination collection.
keys Array ○ The unique identifiers for the keys to move.
newCollectionContractId String ○ The unique identifier for the contract with Akamai under which you deploy the new destination collection.
newCollectionDescription String ○ The description that you provide for the new destination collection.
newCollectionGroupId Integer ○ The unique identifier for the group in Control Center under which you deploy the new destination collection.
newCollectionName String ○ The name that you assign to the new destination collection.

RevokeRestoreKeys

Contains information about keys to revoke or restore.

Download schema: revokeKeysCommand-schema.json

Sample POST request:

{
    "keys": [
        89011,
        89012,
        89013
    ]
}

RevokeRestoreKeys members

Member Type Required Description
RevokeRestoreKeys: Contains information about keys to revoke or restore.
keys Array ○ The unique identifiers for the keys to revoke or restore.

Query

Contains information about the available report filters and objects to report on.

Download schema: report-request-schema.json

Sample POST request:

{
    "filters": {
        "api_key": [
            "403040"
        ]
    }
}

Query members

Member Type Required Description
Query: Contains information about the available report filters and objects to report on.
filters Query.filters ○ Contains information about the custom quota reports filter, with the filter’s name keying an array containing the filter’s set of values.
Query.filters: Contains information about the custom quota reports filter, with the filter’s name keying an array containing the filter’s set of values.
api_key Array ○ The list of API key identifiers.

Report

Contains the response report, including aggregated data and reflecting details on the request.

Download schema: report-response-schema.json

Sample POST response:

{
    "metadata": {
        "name": "rapidkey-by-quota",
        "version": "1",
        "interval": "FIVE_MINUTES",
        "start": "2018-05-16T00:00:00Z",
        "end": "2018-05-18T00:00:00Z",
        "availableDataEnds": "2018-05-17T09:00:50.771902Z",
        "suggestedRetryTime": null,
        "rowCount": 17,
        "objectType": "rapidfile",
        "groupBy": [
            "api_key"
        ],
        "objectIds": [
            "ymdfile"
        ],
        "filters": [
            {
                "name": "api_key",
                "values": [
                    "219002",
                    "245001"
                ]
            }
        ],
        "columns": [
            {
                "name": "groupBy",
                "label": "api_key"
            },
            {
                "name": "quotaUsage",
                "label": "Quota Used"
            }
        ]
    },
    "summaryStatistics": {},
    "data": [
        {
            "api_key": " (244253)",
            "apikeyCollection": "100/hour",
            "time_interval": "0",
            "quotaUsage": "0"
        },
        {
            "api_key": " (244250)",
            "apikeyCollection": "100/twelve hours",
            "time_interval": "2",
            "quotaUsage": "0"
        },
        {
            "api_key": " (224173)",
            "apikeyCollection": "1000/month",
            "time_interval": "5",
            "quotaUsage": "0"
        }
    ]
}

Report members

Member Type Required Description
Report: Contains the response report, including aggregated data and reflecting details on the request.
data Report.data[] ○ The list of report data rows suitable for aggregation. The value of the groupBy array serves as a key for each row to indicate the metric by which the row is grouped and sorted.
metadata Report.metadata ✓ Contains information about the requested data set based on the request’s parameters and the contents of the query object. Provides information for use in the report output.
summaryStatistics Object ✓ Contains summary statistics for a report. This doesn’t apply when running quota reports, in which case the object is always empty.
Report.data[]: The list of report data rows suitable for aggregation. The value of the groupBy array serves as a key for each row to indicate the metric by which the row is grouped and sorted.
api_key String ○ The API key description and the API key identifier in parentheses.
apikeyCollection String ○ The maximum quota allowed per API key and the quota interval in a given key collection.
quotaUsage String ○ The quota used by an API key in a given period.
startdatetime String ○ Indicates the start of each record in a report, in ISO 8601 format.
time_interval Enumeration ○ The identifier for the quota interval, either 0 for an hour, 1 for six hours, 2 for twelve hours, 3 for a day, 4 for a week, or 5 for a month.
Report.metadata: Contains information about the requested data set based on the request’s parameters and the contents of the query object. Provides information for use in the report output.
availableDataEnds String, Null ✓ For unfinalized report data, the ISO 8601 timestamp indicating when the data is available. Otherwise, the value is null for finalized data.
columns Report.metadata.columns[] ✓ The list of interface labels for the data member.
end String ✓ The ISO 8601 timestamp indicating the end date for the requested data. This reflects the value of the Generate a report operation’s end parameter.
filters Report.metadata.filters[] ✓ Contains information about the filters specified in the request.
groupBy Array ✓ The list of fields by which data is grouped and sorted. The groupBy field is specified in each data row.
interval Enumeration ✓ The duration of each record in the report, either FIVE_MINUTES, HOUR, DAY, WEEK, or MONTH. This reflects the value of the Generate a report operation’s interval parameter.
name String ○ The name of the current report type.
objectIds Array ✓ The list of internal identifiers related to reports. For quota reports, the array always contains a single entry: ymdfile.
objectType String ✓ The internal identifier related to reports. For quota reports, the value is always rapidfile.
rowCount Integer ✓ The total number of data records included in the report.
start String ✓ Indicates the start date for the requested data, in ISO 8601 format. This reflects the value of the Generate a report operation’s start parameter.
suggestedRetryTime String, Null ✓ For unfinalized report data, indicates the estimated report completion date, in ISO 8601 format. Otherwise, the value is null for finalized data.
uri String ○ The URL called to get the report data.
version String ○ The version of the current report type.
Report.metadata.columns[]: The list of interface labels for the data member.
label String ○ The interface label to assign to the corresponding name member.
name String ○ The name of the corresponding data member.
Report.metadata.filters[]: Contains information about the filters specified in the request.
name String ○ The name of the filter specified in the request or included in the default set for a given report type.
value Array ○ The list of requested filter values.

ThrottlingCounter

Contains information about a throttling counter.

Download schema: counter-schema.json

Sample POST request:

{
    "id": 61,
    "enabled": true,
    "name": "Books counter",
    "description": "A counter for requests to the books resource within the Bookstore API.",
    "groupId": 105425,
    "throttling": 1000,
    "onOverLimit": "WARN",
    "contractId": "F-IGRAJY",
    "status": "ACTIVE",
    "createdAt": "2019-02-05T08:31:32.659081Z",
    "updatedAt": "2019-02-15T20:12:01.197694Z",
    "createdBy": "bookstore_admin",
    "updatedBy": "bookstore_admin",
    "dirty": false,
    "errorResponse": {
        "overrideDefaults": true,
        "statusCode": 429,
        "body": null,
        "headers": []
    },
    "headers": {
        "sendLimitToClient": false,
        "sendLimitToOrigin": false,
        "sendRateToClient": false,
        "sendRateToOrigin": true
    },
    "rules": [
        {
            "id": 64,
            "type": "ACL_ENTRY",
            "values": [
                "ENDPOINT-290100",
                "RESOURCE-9946",
                "METHOD-43226",
                "METHOD-43227"
            ]
        },
        {
            "id": 61,
            "type": "KEY",
            "values": [
                316013,
                314095,
                314097,
                314098
            ]
        },
        {
            "id": 62,
            "type": "KEY_COLLECTION",
            "values": [
                416013,
                414095,
                414097,
                414098
            ]
        }
    ]
}

ThrottlingCounter members

Member Type Required Description
ThrottlingCounter: Contains information about a throttling counter.
contractId String ✓ The unique identifier for the contract with Akamai under which you created the throttling counter.
createdAt String ○ Read-only. Indicates when the throttling counter was created, in ISO 8601 format.
createdBy String ○ Read-only. The user who created the throttling counter.
description String ○ The description that you provide for the throttling counter. If you specify an empty string in the request or omit this member from the object, the JSON response reflects it as null.
dirty Boolean ○ Read-only. Whether changes to the throttling counter’s status are being propagated to the Akamai network.
enabled Boolean ✓ Whether you enabled the throttling counter.
errorResponse ThrottlingCounter.errorResponse, Null ○ Contains information about a customizable error response.
groupId Integer ✓ The unique identifier for the group in Control Center under which you created the throttling counter.
headers ThrottlingCounter.headers, Null ○ Contains information about the criteria for sending the throttling limit and rate HTTP headers. This value may appear as null if you don’t specify any throttling headers.
id Integer ○ Read-only. The unique identifier for the throttling counter.
name String ✓ The name that you provide for the throttling counter.
onOverLimit Enumeration ✓ The instruction for edge servers on how to handle excessive requests when a throttling limit is reached. Either DENY to reject excessive requests, or WARN to send an alert when excessive requests reach edge servers.
rules ThrottlingCounter.rules[] ○ The throttling conditions that cause the counter to increment.
throttling Integer ✓ The value of the request-per-second limit associated with the throttling counter. If the request count reaches the defined limit, API Gateway rejects any excessive requests with a 429 response until the moving average for this throttling counter diminishes to the set threshold. This usually takes up to ten seconds.
updatedAt String ○ Read-only. Indicates when the throttling counter was updated, in ISO 8601 format.
updatedBy String ○ Read-only. The user who last updated the throttling counter.
ThrottlingCounter.errorResponse: Contains information about a customizable error response.
body String, Null ○ The response body to return in case of the error. The value should have the proper formatting to reflect the content type. For example, in case of a JSON body format, enclose the text in curly brackets ({}). If you specify an empty string in the request or omit this member from the object, the JSON response reflects it as null.
headers ThrottlingCounter.errorResponse.headers[] ○ The list of HTTP headers to return in case of the error. By default, API Gateway returns the Content-Type header with a value of application/problem+json which reflects the default response body. If the body member indicates a different content type, set the Content-Type header to the appropriate value. For example, in case of an XML body, the value could be application/problem+xml.
overrideDefaults Boolean ○ Read-only. Whether you overrode the default error response.
statusCode Integer ✓ The status code to return in case of the error.
ThrottlingCounter.errorResponse.headers[]: The list of HTTP headers to return in case of the error. By default, API Gateway returns the Content-Type header with a value of application/problem+json which reflects the default response body. If the body member indicates a different content type, set the Content-Type header to the appropriate value. For example, in case of an XML body, the value could be application/problem+xml.
name String ✓ The name of the HTTP header to return in case of the error.
value String ✓ The value of the HTTP header to return in case of the error.
ThrottlingCounter.headers: Contains information about the criteria for sending the throttling limit and rate HTTP headers. This value may appear as null if you don’t specify any throttling headers.
sendLimitToClient Boolean ○ Whether to send the X-Throttling-Limit header in a response to a client.
sendLimitToOrigin Boolean ○ Whether to send the X-Throttling-Limit header to your origin.
sendRateToClient Boolean ○ Whether to send the X-Throttling-Rate header in a response to a client.
sendRateToOrigin Boolean ○ Whether to send the X-Throttling-Rate header to your origin.
ThrottlingCounter.rules[]: The throttling conditions that cause the counter to increment.
id Integer ○ The unique identifier for the throttling condition.
type Enumeration ✓ The type of the throttling condition. Either KEY for conditions associated with API keys, KEY_COLLECTION for conditions associated with API collections, or ACL_ENTRY for conditions associated with API endpoints, resources, or HTTP methods.
values Array ✓ The specific values that trigger the throttling condition. If you selected KEY for the type member, specify API key integer IDs. If you selected ACL_ENTRY for the type member, specify strings that represent API endpoints, resources, or HTTP methods.

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 responds with JSON objects that adhere to the HTTP problem details standard. This example shows a validation error, where the type value is a non-navigable URI, and the instance may be useful if you need to communicate about the problem with your Akamai support representative:

{
    "type": "/apikey-manager-api/error-types/validation-error",
    "status": 400,
    "title": "Validation error",
    "instance": "83e2a26b-0ba9-4456-aafe-c063f58b56ea",
    "errors": [
        {
            "type": "/apikey-manager-api/error-types/invalid-size",
            "title": "Invalid size",
            "detail": "size must be between 1 and 2147483647",
            "min": 1,
            "field": "keys",
            "max": 2147483647,
            "rejectedValue": []
        }
    ]
}

HTTP status codes

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

Code Description
200 The operation was successful.
201 Successfully created.
204 Successfully processed request.
400 Bad request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
405 Method not supported.
500 Internal server error.
503 Too many requests. Service is temporarily unavailable.

Error types

This table lists each of the API’s error type strings you may encounter. Problem responses provide this data as the type member, each with this common URL prefix: https://problems.luna.akamaiapis.net/apikey-manager-api/error-types/.

Error Type Description
collection-not-blank-elements The tags array contains at least one empty element and the elements in this array cannot be empty.
contract-not-found The contract ID specified doesn’t exist.
file-not-empty The content value specified during the Import keys operation doesn’t contain any data.
greater-than-max The numerical JSON value is too large.
group-not-found The groupId specified doesn’t exist. For information, see the Identity Management: User Administration API.
invalid-collection-size The maximum number of tags that you can assign to a key collection is 10.
invalid-json-value The JSON value doesn’t meet the validation criteria for the corresponding JSON field.
invalid-length The maximum length of the JSON value is 200 characters.
key-collection-not-unique A key collection with the name already exists.
key-import-contains-duplicate The content value specified during the Import keys operation contains duplicate key data.
key-import-max-count The number of keys that you want to create through the Import keys operation crosses the allowed limit. The maximum number of keys that you can store in your collections is 10000 per one Akamai contract.
key-import-syntax-error The content value specified during the Import keys operation contains syntactic errors. For guidelines on forming the import file, see Import keys.
key-import-unrecognizable-properties The content value specified during the Import keys operation contains properties unrecognizable by the system. For guidelines on forming the import file, see Import keys.
key-import-unsupported-extension The name value specified during the Import keys operation refers to an unsupported extension. The supported extensions are: csv, xml, json.
key-not-unique A key with the value specified already exists.
less-than-min The numerical JSON value is too small.
not-empty The JSON value is empty, and the corresponding JSON field only accepts non-empty values.
not-null The JSON value is null, and the corresponding JSON field doesn’t accept null values.
required-param-missing The JSON value specified as required in the schema is missing from the request body.
resource-not-found A key or collection with the ID specified doesn’t exist.
bad-input The JSON value is of a different data type than expected in the corresponding JSON field.