
- Overview
- Resources
- API summary
- List key collections
- Create a key collection
- Get a key collection
- Edit a key collection
- Delete a key collection
- List collection endpoints
- Edit an ACL
- Edit quota settings
- List keys
- Create keys
- Get a key
- Edit a key
- Import keys
- Generate keys
- Move keys
- Revoke keys
- Restore revoked keys
- Reset key quota
- List tags
- Generate a report
- List throttling counters
- Create a throttling counter
- Get a throttling counter
- Edit a throttling counter
- Delete a throttling counter
- List counter endpoints
- List counter keys
- Data
- Errors
API Keys and Traffic Management API v1
Create and manage API keys. Control your API traffic with quotas and throttling.
Learn more:
Download this API’s RAML and JSON schema descriptors.
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
andgrantedACL
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:
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/ |
Create a key collection | POST | /apikey-manager-api/ |
Get a key collection | GET | /apikey-manager-api/ |
Edit a key collection | PUT | /apikey-manager-api/ |
Delete a key collection | DELETE | /apikey-manager-api/ |
List collection endpoints | GET | /apikey-manager-api/ |
Edit an ACL | PUT | /apikey-manager-api/ |
Edit quota settings | PUT | /apikey-manager-api/ |
Keys | ||
List keys | GET | /apikey-manager-api/ |
Create keys | POST | /apikey-manager-api/ |
Get a key | GET | /apikey-manager-api/ |
Edit a key | PUT | /apikey-manager-api/ |
Import keys | POST | /apikey-manager-api/ |
Generate keys | POST | /apikey-manager-api/ |
Move keys | POST | /apikey-manager-api/ |
Revoke keys | POST | /apikey-manager-api/ |
Restore revoked keys | POST | /apikey-manager-api/ |
Reset key quota | POST | /apikey-manager-api/ |
Tags | ||
List tags | GET | /apikey-manager-api/ |
Reports | ||
Generate a report | POST | /apikey-manager-api/ |
Throttling counters | ||
List throttling counters | GET | /apikey-manager-api/ |
Create a throttling counter | POST | /apikey-manager-api/ |
Get a throttling counter | GET | /apikey-manager-api/ |
Edit a throttling counter | PUT | /apikey-manager-api/ |
Delete a throttling counter | DELETE | /apikey-manager-api/ |
List counter endpoints | GET | /apikey-manager-api/ |
List counter keys | GET | /apikey-manager-api/ |
List key collections
Returns information about all collections available for the current contract and group.
GET /apikey-manager-api/
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/
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
}
}
}
If you don’t already have
contractId
andgroupId
values, run the List contracts and groups operation in the API Endpoints API.From the response array, choose the appropriate pairing of contract and group, and store its
contractId
andgroupId
values.Build a Collection object by specifying the unique
name
,contractId
, andgroupId
values.Optionally specify the
description
value.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/
Sample: /apikey-manager-api/
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
}
}
}
If you don’t already have an
id
value of the appropriate Collection object, run the List key collections operation.Select the appropriate collection from the returned array and store its
id
.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/
Sample: /apikey-manager-api/
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
}
}
}
If you don’t have a full representation of the object you want to modify, run the List key collections operation.
Select the appropriate collection from the returned array and store its
id
.Run the Get a key collection operation for the complete representation of the object.
Modify the Collection object.
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/
Sample: /apikey-manager-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
collectionId |
Integer | 12345 |
The unique identifier for the collection. |
Status 204
If you don’t already have an
id
value, run the List key collections operation.Select the appropriate collection from the returned array and store its
id
.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/
Sample: /apikey-manager-api/
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"
}
]
}
]
}
]
If you don’t already have an
id
value of the appropriate Collection object run the List key collections operation.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/
Sample: /apikey-manager-api/
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
}
}
}
Run the List collection endpoints operation.
If you want to add an endpoint to an ACL, pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndpointId
.If you want to add a resource to an ACL, pick the appropriate resource from the
apiResourceBaseInfo
array and store itsapiResourceLogicId
.If you want to add a method to an ACL, pick the appropriate method from the
methods
array and store itsapiResourceMethodLogicId
.Build an array of the endpoint, resource, and method items that you want to add to an ACL. Prefix their
apiEndpointId
,apiResourceLogicId
, orapiResourceMethodLogicId
values with theENDPOINT-
,RESOURCE-
, orMETHOD-
string. For example,ENDPOINT-1234
. Note: If you add anENDPOINT
,RESOURCE
, orMETHOD
without explicitly specifying its child or parent items, the API adds all its child and any parent items. For example, by adding onlyRESOURCE_1234
, you also add all child methods and the parent endpoint this resource is associated with.If you don’t already have an
id
value of the appropriate Collection object, run the List key collections operation.Select the appropriate collection from the returned array and store its
id
.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/
Sample: /apikey-manager-api/
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
}
}
}
If you don’t already have an
id
value of the appropriate Collection object, run the List key collections operation.Select the appropriate collection from the returned array and store its
id
.Build the Quota object by specifying its
enabled
,value
, andinterval
values.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/
Sample: /apikey-manager-api/
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"
]
}
]
}
Optionally set the
collectionId
query parameter to list keys included in a specific collection.Optionally set the
filter
query parameter to list keys that contain a specific phrase as part of their description, tags, or label.If you want to modify pagination, set the
pageSize
query parameter for the number of records per page, and thepageNumber
.If you want to affect how the output is sorted, set the
sortDirection
query parameter to eitherasc
ordesc
and thesortColumn
query parameter toid
,label
, ordescription
.If you want to list keys of a specific type, set the
keyType
query parameter toAll
,Active
,Revoked
, orPending
.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/
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"
]
}
If you don’t already have an
id
value of the appropriate Collection object, run the List key collections operation.Select the appropriate collection from the returned array and store its
id
.Build a CreateKey object by providing its
value
andcollectionId
values.Optionally you can add new or existing
tags
to the object. Run the List tags operation for a list of existing tags.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/
Sample: /apikey-manager-api/
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"
]
}
Edit a key
Updates information about a key.
PUT /apikey-manager-api/
Sample: /apikey-manager-api/
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"
]
}
If you don’t have a full representation of the object you want to modify, run the List keys operation.
Select the appropriate key from the returned array and store its
id
.Run the Get a key operation for the complete representation of the object.
Modify the Key object.
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/
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:
If you don’t already have an
id
value of the appropriate Collection object, run the List key collections operation.Select the appropriate collection from the returned array and store its
id
.Build an ImportKeys object by providing its
collectionId
,name
, andsize
values.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.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/
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
If you don’t already have an
id
value of the appropriate Collection object, run the List key collections operation.Select the appropriate collection from the returned array and store its
id
.Build a GenerateKeys object by providing its
collectionId
andcount
values.Optionally you can add new or existing
tags
to the object. Run the List tags operation for a list of existing tags.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/
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:
If you don’t already have the
id
values of the appropriate Key objects, run the List keys operation.Select the appropriate keys from the returned array and store their
id
values.Run the List key collections operation.
Select the appropriate collection from the returned array and store its
id
value ascollectionId
.Build a MoveKeys object by specifying the
collectionId
value.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:
If you don’t already have the
id
values of the appropriate Key objects, run the List keys operation.Select the appropriate keys from the returned array and store their
id
values.If you don’t already have
contractId
andgroupId
values, run the List contracts and groups operation in the API Endpoint Definition API.From the response array, choose the appropriate pairing of contract and group, and store its
contractId
andgroupId
values asnewCollectionContractId
, andnewCollectionGroupId
.Build a MoveKeys object by specifying the
newCollectionName
,newCollectionContractId
, andnewCollectionGroupId
values, and optionally thenewCollectionDescription
value.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/
Content-Type: application/json
Object type: RevokeRestoreKeys
Download schema: revokeKeysCommand-schema.json
Request body:
{
"keys": [
89011,
89012,
89013
]
}
Status 204
If you don’t already have the
id
values of the appropriate Key objects, run the List keys operation.Select the appropriate keys from the returned array and store their
id
values.Build a RevokeRestoreKeys object by including all
id
values of the keys that you want to revoke in an array.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/
Content-Type: application/json
Object type: RevokeRestoreKeys
Download schema: revokeKeysCommand-schema.json
Request body:
{
"keys": [
89011,
89012,
89013
]
}
Status 204
If you don’t already have an
id
value of the appropriate Key object, run the List keys operation and set thekeyType
query parameter toRevoked
.Select the appropriate keys from the returned array and store their
id
values.Build a RevokeRestoreKeys object by including all
id
values of the keys that you want to restore in an array.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/
Content-Type: application/json
Object type: Key
Download schema: keysList-schema.json
Request body:
{
"keys": [
"1324149",
"1324150",
"1324151"
]
}
Status 204
If you don’t already have the
id
values of the appropriate Key objects, run the List keys operation.Select the appropriate keys from the returned array and store their
id
values.Build an array of
id
values of all keys that you want to reset quota for.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/
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/
Sample: /apikey-manager-api/
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/
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/
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
]
}
]
}
Build a ThrottlingCounter object by specifying the unique
name
,contractId
andgroupId
values, the allowedthrottling
limit, whether the counter should beenabled
, and the behavior of edge serversonOverLimit
.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/
Sample: /apikey-manager-api/
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
]
}
]
}
If you don’t already have a
counterId
value, run the List throttling counters operation.Select the appropriate throttling counter from the returned array and store its
counterId
.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/
Sample: /apikey-manager-api/
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
]
}
]
}
If you don’t already have a
counterId
value, run the List throttling counters operation.Select the appropriate throttling counter from the returned array and store its
counterId
.Run the Get a throttling counter operation for the complete representation of the object.
Modify the ThrottlingCounter object.
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/
Sample: /apikey-manager-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
counterId |
Integer | 54321 |
The unique identifier for the throttling counter. |
Status 204
If you don’t already have a
counterId
value, run the List throttling counters operation.Select the appropriate throttling counter from the returned array and store its
counterId
.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/
Sample: /apikey-manager-api/
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"
}
]
}
]
}
]
If you don’t already have a
counterId
value, run the List throttling counters operation.Select the appropriate throttling counter from the returned array and store its
counterId
.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/
Sample: /apikey-manager-api/
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"
]
}
]
If you don’t already have a
counterId
value, run the List throttling counters operation.Select the appropriate throttling counter from the returned array and store its
counterId
.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. |
○ | 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. |
○ | 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. |
|||
allow |
Boolean | ○ | Whether to send the X-RateLimit-Limit header in a response when the quota remains. |
allow |
Boolean | ○ | Whether to send the X-RateLimit-Remaining header in a response when the quota remains. |
allow |
Boolean | ○ | Whether to send the X-RateLimit-Reset header in a response when the quota remains. |
deny |
Boolean | ○ | Whether to send the X-RateLimit-Limit header in a response when the quota is full. |
deny |
Boolean | ○ | Whether to send the X-RateLimit-Next header in a response when the quota is full. |
deny |
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. |
○ | 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. |
|||
allow |
Boolean | ○ | Whether to send the X-RateLimit-Limit header in a response when the quota remains. |
allow |
Boolean | ○ | Whether to send the X-RateLimit-Remaining header in a response when the quota remains. |
allow |
Boolean | ○ | Whether to send the X-RateLimit-Reset header in a response when the quota remains. |
deny |
Boolean | ○ | Whether to send the X-RateLimit-Limit header in a response when the quota is full. |
deny |
Boolean | ○ | Whether to send the X-RateLimit-Next header in a response when the quota is full. |
deny |
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. |
quota |
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. |
new |
String | ○ | The unique identifier for the contract with Akamai under which you deploy the new destination collection. |
new |
String | ○ | The description that you provide for the new destination collection. |
new |
Integer | ○ | The unique identifier for the group in Control Center under which you deploy the new destination collection. |
new |
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. |
○ | 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. |
○ | 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. |
✓ | 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. |
summary |
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. |
|||
available |
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. |
✓ | 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. |
✓ | 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. |
suggested |
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 |
Throttling |
○ | 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 |
Throttling |
○ | 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 |
Throttling |
○ | 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 |
Throttling |
○ | 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. |
|||
send |
Boolean | ○ | Whether to send the X-Throttling-Limit header in a response to a client. |
send |
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. |