Key and Quota Management API v1

Create and manage API keys that serve as unique identifiers for API consumers.

Learn more:

Overview

The Key and Quota Management API together with the API Endpoints API allow you to deploy your APIs over the Akamai network. The Key and Quota Management API lets you create and manage API keys that serve as unique identifiers for API consumers. API keys exist inside higher-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 keys can make and you can edit access control lists (ACLs) associated with your API endpoints and resources.

Who should use this API

You can use this API if you need to programmatically create and manage API keys on the Akamai platform, and generate reports with data related to quota usage. The Key and Quota Management API lets you group keys into manageable collections. Inside a collection, you can perform the following operations on keys:

  • Create or generate keys

  • Import keys

  • Edit information about keys

  • Revoke and restore keys

  • Move keys to another collection

  • Filter and sort keys according to various criteria

The Key and Quota Management API allows you to configure the following two additional global options that control access and usage of your API by API consumers who identify with keys from a particular collection:

  • 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. Using this API, you can generate two quota reports that help you learn about the quota usage in your key collections.

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

Getting 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.

Resources

This section provides details on the Key and Quota Management API’s various operations and parameters.

The following list provides a road map of all the conceptual objects you deal with when interacting with the Key and Quota Management API.

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

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

  • 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.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Collections  
List collections GET /apikey-manager-api/v1/collections
Create a collection POST /apikey-manager-api/v1/collections
Get a collection GET /apikey-manager-api/v1/collections/{collectionId}
Update a collection PUT /apikey-manager-api/v1/collections/{collectionId}
Remove a collection DELETE /apikey-manager-api/v1/collections/{collectionId}
List endpoints GET /apikey-manager-api/v1/collections/{collectionId}/endpoints
Update an ACL PUT /apikey-manager-api/v1/collections/{collectionId}/acl
Update quota 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 a key POST /apikey-manager-api/v1/keys
Get a key GET /apikey-manager-api/v1/keys/{keyId}
Update 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}

List collections

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

GET /apikey-manager-api/v1/collections

Status 200 application/json

Object type: Collection

Download schema: keyCollectionListDto-schema.json

Response Body:

[
    {
        "id": 124034,
        "name": "test",
        "contractId": "3-13H55B5",
        "groupId": 1024,
        "description": "fff",
        "keyCount": 0,
        "dirty": false,
        "grantedACL": [],
        "dirtyACL": [],
        "quota": {
            "enabled": false,
            "value": 100,
            "interval": "HOUR_1",
            "headers": {
                "denyLimitHeaderShown": true,
                "denyRemainingHeaderShown": false,
                "denyNextHeaderShown": true,
                "allowLimitHeaderShown": true,
                "allowRemainingHeaderShown": false,
                "allowResetHeaderShown": true
            }
        }
    },
    {
        "id": 104011,
        "name": "aaaa",
        "contractId": "3-13H55B5",
        "groupId": 1024,
        "description": "aaaa",
        "keyCount": 0,
        "dirty": false,
        "grantedACL": [],
        "dirtyACL": [],
        "quota": {
            "enabled": true,
            "value": 100,
            "interval": "HOUR_1",
            "headers": {
                "denyLimitHeaderShown": true,
                "denyRemainingHeaderShown": true,
                "denyNextHeaderShown": true,
                "allowLimitHeaderShown": true,
                "allowRemainingHeaderShown": true,
                "allowResetHeaderShown": true
            }
        }
    },
    {
        "id": 124037,
        "name": "bb",
        "contractId": "3-13H55B5",
        "groupId": 1024,
        "description": "bbbb",
        "keyCount": 0,
        "dirty": false,
        "grantedACL": [],
        "dirtyACL": [],
        "quota": {
            "enabled": false,
            "value": 100,
            "interval": "HOUR_1",
            "headers": {
                "denyLimitHeaderShown": false,
                "denyRemainingHeaderShown": false,
                "denyNextHeaderShown": false,
                "allowLimitHeaderShown": true,
                "allowRemainingHeaderShown": true,
                "allowResetHeaderShown": true
            }
        }
    }
]

Create a collection

Creates an empty collection.

POST /apikey-manager-api/v1/collections

Content-Type: application/json

Object type: Collection

Download schema: keyCollectionDto-schema.json

Request Body:

{
    "name": "InternalCollection",
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "description": "Collection for internal customers"
}

Status 201 application/json

Headers:

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

Object type: Collection

Download schema: keyCollectionDto-schema.json

Response Body:

{
    "id": 58001,
    "name": "InternalCollection",
    "description": "Collection for internal customers",
    "keyCount": 0,
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "dirty": false,
    "grantedACL": [],
    "dirtyACL": []
}

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

  2. Optionally specify the description value.

  3. 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 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 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": 55055,
    "name": "jwt",
    "description": "example",
    "keyCount": 41,
    "dirty": false,
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "grantedACL": [
        "ENDPOINT-240184",
        "RESOURCE-10261",
        "RESOURCE-10260",
        "RESOURCE-10601",
        "RESOURCE-10600"
    ],
    "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 an id value of the appropriate Collection object, run the List 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.

Update a collection

Updates information about 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": 55055,
    "name": "jwt",
    "description": "example",
    "keyCount": 41,
    "dirty": false,
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "grantedACL": [
        "ENDPOINT-240184",
        "RESOURCE-10261",
        "RESOURCE-10260",
        "RESOURCE-10601",
        "RESOURCE-10600"
    ],
    "dirtyACL": [],
    "quota": {
        "enabled": false,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}
Parameter Type Sample Description
URL 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": 55055,
    "name": "jwt",
    "description": "example",
    "keyCount": 41,
    "dirty": false,
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "grantedACL": [
        "ENDPOINT-240184",
        "RESOURCE-10261",
        "RESOURCE-10260",
        "RESOURCE-10601",
        "RESOURCE-10600"
    ],
    "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 have a full representation of the object you want to modify, run the List collections operation.

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

  3. Run the Get a 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.

Remove a 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 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 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 Collection object has been deleted.

List endpoints

Returns information about all endpoints associated with a collection.

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

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

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

Status 200 application/json

Download schema: apiEndpointDto-schema.json

Response Body:

[
    {
        "apiEndPointId": 1234,
        "apiEndPointScheme": "https",
        "description": "Provides information about membership benefits and available services.",
        "apiEndPointName": "Membership Benefits",
        "lockVersion": 179389174,
        "createDate": "2017-09-04T11:49:13.632Z",
        "apiResourceBaseInfo": [
            {
                "description": "resource description",
                "lockVersion": 179389174,
                "apiResourceName": "cloud security",
                "resourcePath": "/resources/{resourceId}",
                "link": "/api-definitions/v1/endpoints/1234/resources/7689",
                "updateDate": "2017-09-04T11:49:13.632Z",
                "createdBy": "rsingama@akamai.com",
                "updatedBy": "yauoid",
                "createDate": "2017-09-04T11:49:13.632Z",
                "apiResourceId": 7689
            }
        ],
        "apiCategoryIds": [
            123,
            125
        ],
        "updateDate": "2017-09-04T11:49:13.632Z",
        "createdBy": "rsahk",
        "updatedBy": "rsahk",
        "apiEndPointHosts": [
            "api-stage.abc.com",
            "api.abc.com"
        ],
        "basePath": "/api/v1"
    },
    {
        "apiEndPointId": 1235,
        "apiEndPointScheme": "https",
        "description": "Provides information about membership benefits and available services.",
        "apiEndPointName": "Membership Benefits",
        "lockVersion": 179389174,
        "createDate": "2017-09-04T11:49:13.632Z",
        "apiResourceBaseInfo": [
            {
                "description": "resource description",
                "lockVersion": 179389174,
                "apiResourceName": "cloud security",
                "resourcePath": "/resources/{resourceId}/hosts",
                "link": "/api-definitions/v1/endpoints/1235/resources/7690",
                "updateDate": "2017-09-04T11:49:13.632Z",
                "createdBy": "rsajj",
                "updatedBy": "yauoid",
                "createDate": "2017-09-04T11:49:13.632Z",
                "apiResourceId": 7690
            }
        ],
        "apiCategoryIds": [
            123,
            125
        ],
        "updateDate": "2017-09-04T11:49:13.632Z",
        "createdBy": "rsahk",
        "updatedBy": "rsahk",
        "apiEndPointHosts": [
            "api-stage.abc.com",
            "api.abc.com"
        ],
        "basePath": "/api/v1"
    }
]

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

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

The response is an array of Endpoint objects.

Update an ACL

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

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

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

Content-Type: application/json

Download schema: aclList-schema.json

Request Body:

[
    "ENDPOINT-183165",
    "ENDPOINT-200159",
    "RESOURCE-9218"
]
Parameter Type Sample Description
URL 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": 55055,
    "name": "jwt",
    "description": "example",
    "keyCount": 41,
    "dirty": false,
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "grantedACL": [
        "ENDPOINT-240184",
        "RESOURCE-10261",
        "RESOURCE-10260",
        "RESOURCE-10601",
        "RESOURCE-10600"
    ],
    "dirtyACL": [],
    "quota": {
        "enabled": false,
        "value": 100,
        "interval": "HOUR_1",
        "headers": {
            "denyLimitHeaderShown": true,
            "denyRemainingHeaderShown": true,
            "denyNextHeaderShown": true,
            "allowLimitHeaderShown": true,
            "allowRemainingHeaderShown": true,
            "allowResetHeaderShown": true
        }
    }
}

  1. Run the List 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. Build an array of the endpoint or resource items that you want to add to an ACL, prefixing their apiEndpointId or apiResourceLogicId values with the ENDPOINT- or RESOURCE- string. For example, ENDPOINT-1234.

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

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

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

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

Update quota

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 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": 55055,
    "name": "jwt",
    "description": "example",
    "keyCount": 41,
    "dirty": false,
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "grantedACL": [
        "ENDPOINT-240184",
        "RESOURCE-10261",
        "RESOURCE-10260",
        "RESOURCE-10601",
        "RESOURCE-10600"
    ],
    "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 an id value of the appropriate Collection object, run the List 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": "test",
    "pageNumber": 1,
    "pageSize": 10,
    "sortColumn": "id",
    "sortDirection": "desc",
    "totalItems": 100,
    "items": [
        {
            "id": 577599,
            "value": "cca5e829-7064-44cf-9655-0900b5523794",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577598,
            "value": "43b84519-56d0-4789-9fe2-f38c4955714f",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": -1,
            "quotaUsageTimestamp": "1970-01-01T00:00:00.000Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577597,
            "value": "7f6579ff-a99e-46f2-8886-619d9f9434bf",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577596,
            "value": "9a1686b8-5a0f-402f-a505-733fac8d293c",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577595,
            "value": "c2545bcd-acf1-4392-a2df-29021ee2cfad",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577594,
            "value": "d90fdc10-117a-4b17-b719-99db9250286d",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577593,
            "value": "742c5efa-4790-4d5f-bc13-3db1bcd42cdd",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577592,
            "value": "466d5bff-63a7-4d1c-8029-672d831ac15d",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577591,
            "value": "7e673a5d-f108-4f78-9abd-72e4cb9d7cb2",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        },
        {
            "id": 577590,
            "value": "781692fe-7193-4a7d-a2ca-47b6e1c2f1d6",
            "label": "sampleLabel",
            "tags": [],
            "collectionName": "Sample collection",
            "collectionId": 19816,
            "description": "test",
            "revoked": false,
            "dirty": false,
            "createdAt": "2017-11-02T08:12:23.891Z",
            "revokedAt": null,
            "terminationAt": null,
            "quotaUsage": 10,
            "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
            "quotaUpdateState": "NONE"
        }
    ]
}

  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 a key

Creates in a collection a single key for which you define a value. To generate multiple keys, see 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": 58002,
    "tags": [
        "single",
        "new"
    ],
    "value": "ef527010-63e8-45ae-91e2-29757180631e",
    "label": "Test key",
    "description": "For test purposes only"
}

Status 201 application/json

Headers:

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

Object type: Key

Download schema: keyDto-schema.json

Response Body:

{
    "id": 89003,
    "value": "cf527010-63e8-45ae-91e2-29757180631e",
    "label": "Weather",
    "tags": [
        "internal",
        "single"
    ],
    "collectionName": "InternalCollection",
    "collectionId": 58002,
    "description": "Key with weather label",
    "revoked": false,
    "dirty": true,
    "createdAt": "2017-09-04T11:49:13.632Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": 10,
    "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
    "quotaUpdateState": "NONE"
}

  1. If you don’t already have an id value of the appropriate Collection object, run the List 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 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": 89003,
    "value": "cf527010-63e8-45ae-91e2-29757180631e",
    "label": "Weather",
    "tags": [
        "internal",
        "single"
    ],
    "collectionName": "InternalCollection",
    "collectionId": 58002,
    "description": "Key with weather label",
    "revoked": false,
    "dirty": true,
    "createdAt": "2017-09-04T11:49:13.632Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": 10,
    "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
    "quotaUpdateState": "NONE"
}

  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.

Update 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": 89003,
    "value": "cf527010-63e8-45ae-91e2-29757180631e",
    "label": "Weather",
    "tags": [
        "internal",
        "single"
    ],
    "collectionName": "InternalCollection",
    "collectionId": 58002,
    "description": "Key with weather label",
    "revoked": false,
    "dirty": true,
    "createdAt": "2017-09-04T11:49:13.632Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": 10,
    "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
    "quotaUpdateState": "NONE"
}
Parameter Type Sample Description
URL 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": 89003,
    "value": "cf527010-63e8-45ae-91e2-29757180631e",
    "label": "Weather",
    "tags": [
        "internal",
        "single"
    ],
    "collectionName": "InternalCollection",
    "collectionId": 58002,
    "description": "Key with weather label",
    "revoked": false,
    "dirty": true,
    "createdAt": "2017-09-04T11:49:13.632Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": 10,
    "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
    "quotaUpdateState": "NONE"
}

  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, the data structure that constitutes the contents of the import file must be embedded in a JSON object.

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": "[\n    {\n        \"value\": \"cf527010-63e8-45ae-91e2-29757180631e\",\n        \"label\": \"Weather \",\n        \"tags\": [\n            \"new\",\n            \"blue\"\n        ]\n    },\n    {\n        \"value\": \"cf557010-63e8-45fg-94e2-29757180631e\",\n        \"label\": \"Weather\",\n        \"tags\": [\n            \"new\",\n            \"red\"\n        ]\n    }\n]",
    "size": 271,
    "collectionId": 58002
}

Status 204

  1. If you don’t already have an id value of the appropriate Collection object, run the List 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, content, and size values.

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

A 204 response confirms that the import operation was successful.

Generate keys

Creates in a collection multiple keys with automatically generated values. To create a single key, see the Create a key operation.

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

Content-Type: application/json

Object type: GenerateKeys

Download schema: generateKeysCommand-schema.json

Request Body:

{
    "collectionId": 58002,
    "tags": [
        "group",
        "generated"
    ],
    "count": 20,
    "incrementLabel": true,
    "label": "GeneratedKeys",
    "description": "Keys for bigger group"
}

Status 204

  1. If you don’t already have an id value of the appropriate Collection object, run the List 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 a collection to either an existing collection or a new one.

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

Content-Type: application/json

Object type: MoveKeys

Download schema: moveKeysCommand-schema.json

Request Body:

{
    "newCollectionName": "NewCollection",
    "newCollectionDescription": "New collection of moved keys",
    "newCollectionContractId": "3-13H55B",
    "newCollectionGroupId": 1024,
    "keys": [
        89016,
        89015,
        89014
    ]
}

Status 204

Gather prerequisites:

  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.

To move keys to an existing collection:

  1. Run the List collections operation.

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

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

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

To move keys to a new collection:

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

  2. 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 are 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:

[
    "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 a key or Generate keys operation.

GET /apikey-manager-api/v1/tags

Status 200 application/json

Download schema: tagsList-schema.json

Response Body:

[
    "tag1",
    "generated",
    "tag4",
    "tag2",
    "tag3"
]

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": [
            "1234"
        ]
    }
}
Parameter Type Sample Description
URL 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 The ISO–8601 timestamp indicating the end date for the report data. 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 The ISO–8601 timestamp indicating the start date for the report data.

Status 200 application/json

Object type: Report

Download schema: report-response-schema.json

Response Body:

{
    "metadata": {
        "name": "rapidkey-by-quota",
        "version": "1",
        "groupBy": [
            "api_key"
        ],
        "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,
        "filters": [
            {
                "name": "api_key",
                "values": [
                    "219002",
                    "245001"
                ]
            }
        ],
        "columns": [
            {
                "name": "groupBy",
                "label": "api_key"
            },
            {
                "name": "quotaUsage",
                "label": "Quota Used"
            }
        ],
        "objectType": "rapidfile",
        "objectIds": [
            "ymdfile"
        ]
    },
    "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"
        }
    ],
    "summaryStatistics": {}
}

Data

This section details the JSON objects that the Key and Quota Management API provides as data.

Download the JSON schemas for this API.

The data schema tables below 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": 55055,
    "name": "jwt",
    "description": "example",
    "keyCount": 41,
    "dirty": false,
    "contractId": "3-13H55B5",
    "groupId": 1024,
    "grantedACL": [
        "ENDPOINT-240184",
        "RESOURCE-10261",
        "RESOURCE-10260",
        "RESOURCE-10601",
        "RESOURCE-10600"
    ],
    "dirtyACL": [],
    "quota": {
        "enabled": false,
        "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 provision the collection.
description String ○ The description that you provide for the collection.
dirty Boolean ○ Whether the collection contains changes that are being propagated to the Akamai network.
dirtyACL Array ○ The endpoints or resources with ACL changes that are being propagated to the Akamai network.
grantedACL Array ○ The endpoints or resources accessible to API consumers that identify with keys included in the collection.
groupId Integer ✓ The unique identifier for the group in the Luna portal under which you provision the collection.
id Integer ○ The unique identifier for the collection.
keyCount Integer ○ The number of keys included in the collection.
name String ✓ The name of the collection.
quota Collection.quota ○ 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": 89003,
    "value": "cf527010-63e8-45ae-91e2-29757180631e",
    "label": "Weather",
    "tags": [
        "internal",
        "single"
    ],
    "collectionName": "InternalCollection",
    "collectionId": 58002,
    "description": "Key with weather label",
    "revoked": false,
    "dirty": true,
    "createdAt": "2017-09-04T11:49:13.632Z",
    "revokedAt": null,
    "terminationAt": null,
    "quotaUsage": 10,
    "quotaUsageTimestamp": "2017-11-02T09:12:23.891Z",
    "quotaUpdateState": "NONE"
}

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 ○ The name of the collection that includes the key.
createdAt String ○ Read-only. The ISO 8601 timestamp for when the key was created.
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.
label String ○ The label that you assign to the key.
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. The ISO 8601 timestamp for when the key’s quota was updated.
revoked Boolean ○ Read-only. Whether you revoked the key.
revokedAt String, Null ○ Read-only. The ISO 8601 timestamp for when the key was revoked.
tags Array ○ The additional categories associated with the key that you can use as filters.
terminationAt String, Null ○ Read-only. The ISO 8601 timestamp for when the key will be deleted.
value String ○ The value of the key.

CreateKey

Contains information about a key to create.

Download schema: createNewKeyCommand-schema.json

Sample POST request:

{
    "collectionId": 58002,
    "tags": [
        "single",
        "new"
    ],
    "value": "ef527010-63e8-45ae-91e2-29757180631e",
    "label": "Test key",
    "description": "For test purposes only"
}

CreateKey members

Member Type Required Description
CreateKey: Contains information about a key to create.
collectionId Integer ✓ The unique identifier for the collection that includes the key.
collectionName String ○ The name of the collection that includes the key.
createdAt String ○ Read-only. The ISO 8601 timestamp for when the key was created.
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.
label String ○ The label that you assign to the key.
revoked Boolean ○ Read-only. Whether you revoked the key.
revokedAt String ○ Read-only. The ISO 8601 timestamp for when the key was revoked.
tags Array ○ The additional categories associated with the key that you can use as filters.
terminationAt String ○ Read-only. The ISO 8601 timestamp for when the key will be deleted.
value String ✓ The value of the key.

ImportKeys

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

Download schema: importKeysCommand-schema.json

Sample POST request:

{
    "name": "import.json",
    "content": "[\n    {\n        \"value\": \"cf527010-63e8-45ae-91e2-29757180631e\",\n        \"label\": \"Weather \",\n        \"tags\": [\n            \"new\",\n            \"blue\"\n        ]\n    },\n    {\n        \"value\": \"cf557010-63e8-45fg-94e2-29757180631e\",\n        \"label\": \"Weather\",\n        \"tags\": [\n            \"new\",\n            \"red\"\n        ]\n    }\n]",
    "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.
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.

Download schema: generateKeysCommand-schema.json

Sample POST request:

{
    "collectionId": 58002,
    "tags": [
        "group",
        "generated"
    ],
    "count": 20,
    "incrementLabel": true,
    "label": "GeneratedKeys",
    "description": "Keys for bigger group"
}

GenerateKeys members

Member Type Required Description
GenerateKeys: Contains information about keys to generate.
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. The ISO 8601 timestamp for when the key was created.
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 an automatic increment is appended to the label of each key.
label String ○ The label that you assign to the key.
revoked Boolean ○ Read-only. Whether you revoked the key.
revokedAt String ○ Read-only. The ISO 8601 timestamp for when the key was revoked.
tags Array ○ The additional categories associated with the key that you can use as filters.
terminationAt String ○ Read-only. The ISO 8601 timestamp for when the key will be deleted.
value String ○ The value of the key.

MoveKeys

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

Download schema: moveKeysCommand-schema.json

Sample POST request:

{
    "newCollectionName": "NewCollection",
    "newCollectionDescription": "New collection of moved keys",
    "newCollectionContractId": "3-13H55B",
    "newCollectionGroupId": 1024,
    "keys": [
        89016,
        89015,
        89014
    ]
}

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 provision 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 the Luna portal under which you provision 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": [
            "1234"
        ]
    }
}

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",
        "groupBy": [
            "api_key"
        ],
        "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,
        "filters": [
            {
                "name": "api_key",
                "values": [
                    "219002",
                    "245001"
                ]
            }
        ],
        "columns": [
            {
                "name": "groupBy",
                "label": "api_key"
            },
            {
                "name": "quotaUsage",
                "label": "Quota Used"
            }
        ],
        "objectType": "rapidfile",
        "objectIds": [
            "ymdfile"
        ]
    },
    "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"
        }
    ],
    "summaryStatistics": {}
}

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 is not applicable for quota reports and 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 ○ The ISO–6801 timestamp indicating the start of each record in a report.
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 that indicates the date until which 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 ✓ The ISO–8601 timestamp indicating the start date for the requested data. This reflects the value of the Generate a report operation’s start parameter.
suggestedRetryTime String, Null ✓ For unfinalized report data, the ISO–8601 timestamp that indicates the estimated report completion date. Otherwise, the value is null for finalized data.
uri String ○ The URL called to retrieve 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.

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

The table below lists the common error types that you can encounter and their corresponding descriptions. Each name in the column on the left represents a string that appears after the following URL prefix in the type member: 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 that you specified does not exist.
file-not-empty The content value that you specified during the Import keys operation does not contain any data.
greater-than-max The numerical JSON value is too large.
group-not-found The Luna group ID that you specified does not exist.
invalid-collection-size The maximum number of tags that you can associate with a key collection is 10.
invalid-json-value The JSON value does not 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 that you specified already exists.
key-import-contains-duplicate The content value that you 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 that you 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 that you 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 that you 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 that you 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 does not 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 that you specified does not exist.
bad-input The JSON value is of a different data type than expected in the corresponding JSON field.

Last modified: 1/2/2019