Cloud Access Manager API v1

Securely store and manage access keys for cloud origins independent of your property.

Learn more:


Overview

The Cloud Access Manager (CAM) API connects the Akamai Intelligent Platform and your cloud provider. Use CAM to enable cloud origin authentication and securely store and manage your cloud provider origin credentials as access keys. You can easily select an access key in the Origin Characteristics behavior when creating a Property Manager property for your Akamai product, eliminating the need to manually provide the credentials. You can use the same access key between several properties, for Akamai products that offer support for the Origin Characteristics behavior.

You can also rotate to a new version of an access key by updating its authentication credentials.

Supported cloud providers

Currently, Cloud Access Manager supports these signing processes used by cloud providers to authenticate requests:

  • Amazon Web Services (AWS). CAM supports the V4 signing process.
  • Google Cloud Storage (GCS) in interoperability mode. CAM supports the pre-release V4 signing process.

Get started

To configure this API for the first time:

  • Get hold of the credentials associated with your cloud provider account. You’ll need them to authenticate requests to a cloud origin.

  • Review Get Started with APIs. You use the Identity and Access Management tool in Akamai Control Center to set up access for any Akamai API, as well as gather some information you’ll need:

    • Set up client tokens for access. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

    • Verify you have the API service named Cloud Access Manager, and its access level is set to READ-WRITE. This gives you access to all of the operations in this API.

    • Note your Group name. In the Identity and Access Management interface, Click Show additional details and review the Groups table to see a list of groups. Make note of the Group name for your applicable group.

      >__Note__: If you have access to several groups and are unsure of which one to use, talk to your local Akamai administrator, or contact your Akamai account representative.

  • Get your groupId. Several operations in this API require this value. You can find it using the Identity Management: User Administration API:

    1. List groups.

    2. In the response, search for the Group name you noted. Store the associated groupId value.

  • Get your contractId. Several operations in this API require this value. You can find your contractId using the Contract API:

    1. List contracts. If you only have one, you’re done. Store this as your contractId. If you have more than one, make note of these values and continue.

    2. List products per contract. Set the {contractId} variable to one you’ve noted.

    3. Look for a marketingProductId of Cloud Access Manager in the response. If you find it, this contract has CAM enabled, and you can use this contractId.

    >__Note__: If you’re not sure of the right contract to use, or you see CAM on more than one contract, check with your local Akamai administrator or contact your Akamai account representative.

API concepts

Familiarize yourself with some of the common terms used in this API:

  • Access Keys. You use this API to store your long-term credentials for AWS or GCS as an access key. You use an access key to sign and authenticate requests to these cloud providers. An access key is a combination of the access key ID and secret access key with AWS, or the access ID and secret for GCS.

  • Contracts. Each account features one or more contracts, each of which has a fixed term of service during which specified Akamai products and modules are active. You need a contract’s unique contractId to access some of the CAM API’s operations. See Get started for details on obtaining this value.

  • Groups. Each account features a hierarchy of groups, which control access to Property Manager properties and help consolidate reporting functions, typically mapping to an organizational hierarchy. Using either Control Center or the Identity Management: User Administration API, account administrators can assign properties to specific groups, each with its own set of users and accompanying roles. Your access to any given property depends on the role set for you in its group. You need a group’s groupId to access some of the CAM API’s operations. See Get started for details on obtaining this value.

  • PCI-compliant. An enhanced, secure deployment network that provides TLS and HTTPS functionality. It meets the security standards required to deliver payment card industry (PCI) data. For more information on how this network delivers content, see “Enhanced TLS” in a comparison of TLS offerings.

    Note: To use this deployment network with your access keys, your contract needs to support serving traffic with Enhanced TLS certificates. Also, you need to create an Enhanced TLS certificate for your hostnames in the Certificate Provisioning System and select that certificate when adding these hostnames to your property. See Create and edit certificates.

  • PCI-noncompliant. A standard, secure deployment network that provides TLS and HTTPS functionality. While it’s secure, it doesn’t support delivery of PCI data. For more information on how this network delivers content, see “Standard TLS” in a comparison of TLS offerings.

  • Property. The individual property in Property Manager where you assign an access key. You set up a rule in this property with relevant match criteria for requests and configure the Origin Characteristics behavior in that rule to apply the key.

  • Version. The version of an access key. You can rotate an access key to a new version and you can have up to two versions of a single access key.

API Hypermedia

Some of the API’s data objects feature embedded link relations that provide URL paths that allow direct navigation to an object. For example, when you get an access key status, some items within the list include a link member, as shown here:

"accessKey": {
    "accessKeyUid": 12345,
    "link": "/cam/v1/access-keys/12345"
},
"accessKeyVersion": {
    "accessKeyUid": 12345,
    "version": 1,
    "link": "/cam/v1/access-keys/12345/versions/1"
}

This link responds to a GET request for a specific accessKey or accessKeyVersion.

Rate limiting

The CAM API imposes a rate-limiting constraint of 300 requests per minute to ensure even distribution of system resources. Exceeding this limit results in a 429 error response. You may also see a 503 error response.

  • X-RateLimit-Limit: 300 requests per minute.

  • X-RateLimit-Remaining: The number of remaining requests allowed during the period.

  • X-RateLimit-Next: Once you’ve reached the X-RateLimit-Limit, this represents the time you can issue another individual request. The X-RateLimit-Remaining gradually increases and becomes equal to X-RateLimit-Limit again.

Resource limiting

CAM imposes these limits on access keys:

  • Access keys. You can have a maximum of 50 access keys per contract.

  • Versions per access key. You can have a maximum of two active versions of an access key.

In some cases, you may be able to override these limits. Contact your Akamai representative for more information.

Asynchronous requests

In many cases, diagnostic data can’t be pre-cached, and Akamai edge servers need to dynamically assemble it for you. This introduces significant latencies when performing some requests. Requests can run minutes long, and can time out. To address this problem, the CAM API addresses data asynchronously with some of its operations. The initial response to these operations contains the requestId and retryAfter objects. You also get a response header that includes the Location and Retry-After values. For example, a successful request to create a new access key returns these components:

  • The response body:

    {
        "requestId": 195,
        "retryAfter": 4
    }
    
  • The response headers:

    Location: /cam/v1/access-key-create-requests/6477
    Retry-After: 4
    

Use this data in a later request to poll the status of the initial request. You can use the requestId from the response to check status, but you should wait the retryAfter number of seconds before you do. Additionally, you can use the Location path from the response header as an API hypermedia link in a GET operation. You should also wait the Retry-After number of seconds.

The API provides this set of asynchronous operations:

POST async request GET request status
Create an access key Get the status of an access key job
Create an access key version Get the status of an access key version job

Note: The delete an access key version and property lookup-related operations also offer asynchronous requests, but the support is applied differently. See these resource’s specific entries to see if you need to apply a different method.

Usage examples

These examples show you how to create an access key and rotate it to a new version.

Create and apply an access key

This example shows how to create an access key and apply it in Property Manager:

  1. Get authentication details from your cloud provider.

  2. Run the create an access key operation. Store the accessKeyName and requestId values. Wait the retryAfter number of seconds before continuing to the next step.

  3. Get an access key status using the stored requestId. Repeat this until processingStatus is DONE in the response. Review the accessKeyVersion object and store the link value.

    "processingStatus": "DONE",
    "requestedBy": "jdoe",
    "requestDate": "2021-02-26T13:34:36.715643Z",
    "accessKey": {
        "accessKeyUid": 12345,
        "link": "/cam/v1/access-keys/12345"
    },
    "accessKeyVersion": {
        "accessKeyUid": 12345,
        "version": 1,
        "link": "/cam/v1/access-keys/12345/versions/1"
    }
    
  4. Wait for 10 minutes and call the link with a GET:

    GET /cam/v1/access-keys/12345/versions/1
    
  5. If necessary, repeat step 4 until deploymentStatus is ACTIVE. Store the versionGuid from the response:

    {
        "accessKeyUid": 12345,
        "versionGuid": "1a2b3456-7890-12cd-345-6e7f89012g13",
        "version": 1,
        "cloudAccessKeyId": null,
        "deploymentStatus": "ACTIVE",
        "createdBy": "jdoe",
        "creationDate": "2021-02-26T13:34:37.916873Z"
    }
    
  6. Follow the Property Manager API (PAPI) workflow to create a new property or edit an existing one. Store the propertyId and version set for the property.

  7. Update the rule tree for the property to configure the originCharacteristics behavior:

    • Determine the rule and match criteria you want to use. The required default rule applies to all requests. You can also include an additional rules array and define custom match criteria.

    • Include the originCharacteristics behavior in the behaviors array of your chosen rule. Set country to the geographical location of your origin server to optimize access to it. Set the authenticationMethod to the applicable cloud provider, AWSV4 for Amazon Web Services or, GCS_HMAC_AUTHENTICATION for Google Cloud Services. Set accessKeyEncryptedStorage to true to enable secure use of access keys. Include the gcsAccessKeyVersionGuid member for GCS, or the awsAccessKeyVersionGuid member for AWS and set it to the versionGuid you stored earlier.

      "rules": {
          "name": "default",
          "criteria": [],
          "children": [],
          "options": {
              "is_secure": true
          },
          "behaviors": [
              {
                  "name": "originCharacteristics",
                  "options": {
                      "country": "NORTH_AMERICA",
                      "authenticationMethod": "GCS_HMAC_AUTHENTICATION",
                      "accessKeyEncryptedStorage": true,
                      "gcsAccessKeyVersionGuid": "1a2b3456-7890-12cd-345-6e7f89012g13"
                  }
              },
              {
                  "name": "cpCode",
                  "options": {
                      "value": {
                          "id": 12345,
                          "name": "my CP code"
                      }
                  }
              }
          ]
      }
      
  8. You can further customize the rule tree in your property to meet your needs. See the PAPI feature catalog for details on available behaviors.

  9. Activate your property on the STAGING network for testing.

  10. When you’re satisfied with your property, activate it on the PRODUCTION network to go live.

Rotate an access key to a new version

This example shows how to rotate an access key from version 1 to version 2 and apply it in Property Manager. It’s a best practice to rotate your cloud provider credentials periodically. You may also need to do this if the credentials have expired or been compromised.

  1. Get new authentication details details from your cloud provider.

  2. Create an access key version. Store the requestId returned in the response.

  3. Get an access key version status using the stored requestId. Verify that processingStatus is DONE. Review the accessKeyVersion object and store the link value.

    {
        "processingStatus": "DONE",
        "requestedBy": "jdoe",
        "requestDate": "2021-02-26T14:54:38.622074Z",
        "accessKeyVersion": {
            "accessKeyUid": 12345,
            "version": 2,
            "link": "/cam/v1/access-keys/12345/versions/2"
        }
    }
    
  4. Wait for 10 minutes and call the link with a GET:

    GET /cam/v1/access-keys/12345/versions/2
    
  5. If necessary, repeat step 4 until deploymentStatus is ACTIVE. Store the versionGuid from the response.

    {
        "accessKeyUid": "12345",
        "versionGuid": "2b3c4567-8901-23de-456-7f8g90123h45",
        "version": 2,
        "cloudAccessKeyId": null,
        "deploymentStatus": "ACTIVE",
        "createdBy": "jdoe",
        "creationDate": "2021-02-26T13:34:37.916873Z"
    }
    
  6. Use the accessKeyUid and its previous version to perform a property lookup request. This shows you all of the active properties that are using this version of the key. Store the propertyId for each.

  7. Use the Property Manager API to get the existing rule tree for a property that has CAM activated in the Origin Characteristics behavior. Store the response output.

  8. Update the rule tree and use the existing rule tree’s stored response output as the request body. Locate the originCharacteristics behavior in the request body content. Change the gcsAccessKeyVersionGuid or awsAccessKeyVersionGuid to the new versionGuid.

    "behaviors": [
        {
            "name": "originCharacteristics",
            "options": {
                "country": "NORTH_AMERICA",
                "authenticationMethod": "GCS_HMAC_AUTHENTICATION",
                "accessKeyEncryptedStorage": true,
                "gcsAccessKeyVersionGuid": "2b3c4567-8901-23de-456-7f8g90123h45"
            }
        },
        {
            "name": "cpCode",
            "options": {
                "value": {
                    "id": 12345,
                    "name": "my CP code"
                }
            }
        }
    ]
    
  9. Repeat steps 7–8 for each remaining propertyId.

  10. Activate each property on the STAGING network for testing.

  11. When you’re satisfied, activate each updated property on the PRODUCTION network to go live.

  12. After each updated property is live in production, use the CAM API to delete the old access key version. You no longer need it.

Resources

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

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Access keys  
List access keys GET /cam/v1/access-keys{?versionGuid}
Create an access key POST /cam/v1/access-keys
Get an access key GET /cam/v1/access-keys/{accessKeyUid}
List access key versions GET /cam/v1/access-keys/{accessKeyUid}/versions
Create an access key version POST /cam/v1/access-keys/{accessKeyUid}/versions
Get an access key version GET /cam/v1/access-keys/{accessKeyUid}/versions/{version}
Delete an access key version DELETE /cam/v1/access-keys/{accessKeyUid}/versions/{version}
Perform a property lookup request GET /cam/v1/access-keys/{accessKeyUid}/versions/{version}/properties
Get an ID for an asynchronous property lookup request GET /cam/v1/access-keys/{accessKeyUid}/versions/{version}/property-lookup-id
Access key status requests  
Get the status of an access key job GET /cam/v1/access-key-create-requests/{requestId}
Access key version status requests  
Get the status of an access key version job GET /cam/v1/access-key-version-create-requests/{requestId}
Property lookups  
Perform a property lookup request asynchronously GET /cam/v1/property-lookups/{lookupId}

List access keys

Returns detailed information about all access keys available to the current user account.

GET /cam/v1/access-keys{?versionGuid}

Sample: /cam/v1/access-keys?versionGuid=ef8e433a–677c–21eb-a7f2-bbb9245556b4

Parameter Type Sample Description
Optional query parameters
versionGuid String ef8e433a-677c-21eb-a7f2-bbb9245556b4 The unique identifier assigned to an access key version.

Status 200 application/json

Object type: AccessKey

Download schema: access-keys.json

Response body:

{
    "accessKeys": [
        {
            "accessKeyUid": 56514,
            "groups": [
                {
                    "groupId": 19715,
                    "groupName": "Sales",
                    "contractIds": [
                        "1-7FALA"
                    ]
                }
            ],
            "authenticationMethod": "AWS4_HMAC_SHA256",
            "accessKeyName": "Sales-s3",
            "note": "Sales key note",
            "creationDate": "2021-02-24T09:09:52.782555Z",
            "createdBy": "jdoe",
            "networkConfiguration": {
                "additionalCdn": "RUSSIA_CDN",
                "securityNetwork": "ENHANCED_TLS"
            },
            "latestVersion": 1
        },
        {
            "accessKeyUid": 56512,
            "groups": [
                {
                    "groupId": 176670,
                    "groupName": "Smarthomes",
                    "contractIds": [
                        "1-7FALA"
                    ]
                }
            ],
            "authenticationMethod": "AWS4_HMAC_SHA256",
            "accessKeyName": "Home automation | s3",
            "note": "Home automation key note",
            "creationDate": "2021-02-26T09:09:15.428314Z",
            "createdBy": "jdoe",
            "networkConfiguration": {
                "additionalCdn": null,
                "securityNetwork": "ENHANCED_TLS"
            },
            "latestVersion": 3
        }
    ]
}

Create an access key

Creates a new access key. An access key’s name needs to be unique within a user account. Once an access key has been created, it’s available on both the staging and production Akamai networks.

POST /cam/v1/access-keys

Content-Type: application/json

Object type: AccessKey

Download schema: access-key-create-request.json

Request body:

{
    "contractId": "1-7FALA",
    "groupId": 10725,
    "authenticationMethod": "AWS4_HMAC_SHA256",
    "networkConfiguration": {
        "securityNetwork": "ENHANCED_TLS",
        "additionalCdn": "RUSSIA_CDN"
    },
    "accessKeyName": "Sales-s3",
    "credentials": {
        "cloudAccessKeyId": "AKAMAICAMKEYID1EXAMPLE",
        "cloudSecretAccessKey": "cDblrAMtnIAxN/g7dF/bAxLfiANAXAMPLEKEY"
    }
}

Status 202 application/json

Headers:

Location: /cam/v1/access-key-create-requests/6477
Retry-After: 4

Download schema: access-key-create-response.json

Response body:

{
    "requestId": 195,
    "retryAfter": 4
}
  1. Gather your groupId and contractId values and get authentication details from your cloud provider. See Get started for details.

  2. Build a new AccessKey object.

  3. POST the object to /cam/v1/access-keys.

  4. You can optionally perform a GET to the Location header in the response to check the request’s status.

The response also includes these headers:

  • Location. This is a URL link that you can use in a GET request to check the status of the create operation.
  • Retry-After. This is the number of seconds you should wait before using the Location path to check status. This delay is in place to ensure you get accurate, up-to-date information.

>Tip: For an example workflow using this operation, see Create and apply an access key.

Get an access key

Returns details for a specific access key.

GET /cam/v1/access-keys/{accessKeyUid}

Sample: /cam/v1/access-keys/12345

Parameter Type Sample Description
URL path parameters
accessKeyUid Integer 12345 The unique identifier Akamai assigns to an access key.

Status 200 application/json

Object type: AccessKey

Download schema: access-key.json

Response body:

{
    "accessKeyUid": 12345,
    "groups": [
        {
            "groupId": 19715,
            "groupName": "Sales",
            "contractIds": [
                "1-7FALA"
            ]
        }
    ],
    "authenticationMethod": "AWS4_HMAC_SHA256",
    "accessKeyName": "Sales-s3",
    "note": "Sales key note",
    "creationDate": "2021-02-26T13:34:36.770624Z",
    "createdBy": "jdoe",
    "networkConfiguration": {
        "additionalCdn": "RUSSIA_CDN",
        "securityNetwork": "ENHANCED_TLS"
    },
    "latestVersion": 1
}
  1. Run the List access keys operation.

  2. Store the accessKeyUid for the relevant access key.

  3. Make a GET request to /cam/v1/access-keys/{accessKeyUid}.

The operation responds with an AccessKey object.

List access key versions

Returns detailed information about all of the versions for a specific access key.

GET /cam/v1/access-keys/{accessKeyUid}/versions

Sample: /cam/v1/access-keys/12345/versions

Parameter Type Sample Description
URL path parameters
accessKeyUid Integer 12345 The unique identifier Akamai assigns to an access key.

Status 200 application/json

Object type: AccessKeyVersion

Download schema: access-key-versions.json

Response body:

{
    "accessKeyVersions": [
        {
            "accessKeyUid": 12345,
            "versionGuid": "af434285-7841-11eb-817b-1f41209f67ec",
            "version": 2,
            "cloudAccessKeyId": null,
            "deploymentStatus": "PENDING_ACTIVATION",
            "createdBy": "jdoe",
            "creationDate": "2021-02-26T14:48:27.355346Z"
        },
        {
            "accessKeyUid": 12345,
            "versionGuid": "5f1c8194-7837-11eb-817b-1b3f28104c18",
            "version": 1,
            "cloudAccessKeyId": null,
            "deploymentStatus": "ACTIVE",
            "createdBy": "jdoe",
            "creationDate": "2021-02-26T13:34:37.916873Z"
        }
    ]
}
  1. Run the List access keys operation.

  2. Store the accessKeyUid for the relevant access key.

  3. Make a GET request to /cam/v1/access-keys/{accessKeyUid}/versions.

The operation responds with an AccessKeyVersion object.

Create an access key version

Rotates an access key to a new version. You should only need to do this if your cloud provider credentials have changed, for example because they’ve expired or been compromised. Only two versions of an access key can be active at a time. After you’ve rotated to a new version and applied it in Property Manager, you should delete the older version.

POST /cam/v1/access-keys/{accessKeyUid}/versions

Sample: /cam/v1/access-keys/12345/versions

Content-Type: application/json

Object type: AccessKeyVersion

Download schema: access-key-credentials.json

Request body:

{
    "cloudAccessKeyId": "AKAMAICAMKEYID2EXAMPLE",
    "cloudSecretAccessKey": "cDdrcAMtrIAvN/h7dF/bAxLfiANAXAMPLEKEY"
}
Parameter Type Sample Description
URL path parameters
accessKeyUid Integer 12345 The unique identifier Akamai assigns to an access key.

Status 202 application/json

Headers:

Location: /cam/v1/access-key-version-create-requests/1686
Retry-After: 6

Download schema: access-key-version-create-response.json

Response body:

{
    "requestId": 227,
    "retryAfter": 6
}
  1. Run the List access keys operation and store the relevant key’s accessKeyUid.

  2. Run the List access key versions operation using the stored accessKeyUid. Review available versions, including their current deploymentStatus. Only two versions of an access key can be supported. A key is currently supported if its deploymentStatus is ACTIVE, PENDING_ACTIVATION, or PENDING_DELETION. With the latter two statuses, you need to wait until they complete that process. Delete any unnecessary version before you create a new one. To see the currently applied version of a key, run the List access keys operation and review the latestVersion object.

  3. Get new authentication details from your cloud provider. See Get started for details.

  4. Build a POST body version of the AccessKeyVersion object.

  5. POST the object to /cam/v1/access-keys/{accessKeyUid}/versions.

  6. You can optionally perform a GET to the Location header in the response to check the request’s status.

The response also includes these headers:

  • Location. This is a URL link that you can use in a GET request to check the status of the create version operation.
  • Retry-After. This is the number of seconds you should wait before using the Location path to check status. This delay is in place to ensure you get accurate, up-to-date information.

After you’ve rotated the access key and it’s in ACTIVE status, you need to apply it in your property in Property Manager. See Rotate an access key to a new version for an example of this process.

Get an access key version

Returns detailed information for a specific version of an access key.

GET /cam/v1/access-keys/{accessKeyUid}/versions/{version}

Sample: /cam/v1/access-keys/12345/versions/2

Parameter Type Sample Description
URL path parameters
accessKeyUid Integer 12345 The unique identifier Akamai assigns to an access key.
version Integer 2 The version number of the access key.

Status 200 application/json

Download schema: access-key-version.json

Response body:

{
    "accessKeyUid": 12345,
    "versionGuid": "5f1c8194-7837-11eb-817b-1b3f28104c18",
    "version": 1,
    "cloudAccessKeyId": null,
    "deploymentStatus": "ACTIVE",
    "createdBy": "jdoe",
    "creationDate": "2021-02-26T13:34:37.916873Z"
}
  1. Run the List access keys operation and store the accessKeyUid for the relevant key.

  2. Run the List access key versions operation.

  3. Locate the version you want and store its version.

  4. Send a GET operation to /cam/v1/access-keys/{accessKeyUid}/versions/{version}.

The operation responds with an AccessKeyVersion object.

Delete an access key version

Deletes a specific version of an access key. This operation works asynchronously. If you receive a successful 202 response, the request has been accepted and it’s been added to the queue for deletion. You can use the Location header that’s returned in the response to check the status of the request. See the Steps content for complete details.

DELETE /cam/v1/access-keys/{accessKeyUid}/versions/{version}

Sample: /cam/v1/access-keys/12345/versions/2

Parameter Type Sample Description
URL path parameters
accessKeyUid Integer 12345 The unique identifier Akamai assigns to an access key.
version Integer 2 The version number of the access key.

Status 202 application/json

Headers:

Location: /cam/v1/access-keys/12345/versions/1

Download schema: access-key-version.json

Response body:

{
    "accessKeyUid": 12345,
    "versionGuid": "636af3f2-7812-11eb-817b-b5459049a617",
    "version": 1,
    "cloudAccessKeyId": null,
    "deploymentStatus": "PENDING_DELETION",
    "createdBy": "jdoe",
    "creationDate": "2021-02-26T09:09:53.762230Z"
}
  1. Run the List access keys operation and locate the relevant key.

  2. Store the key’s accessKeyUid.

  3. Run the List access key versions operation using the stored accessKeyUid.

  4. Store the version for the version you want to delete.

  5. Run the Perform a property lookup request operation. There can be up to a five minute delay for a response. If you see any properties arrays in the response, the target version is still in use in a Property Manager property. Run the Create an access key version to create a new version of the key before deleting this version.

>Note: This step is optional. If you try to delete an access key that’s in use in a property, you’ll receive an error message.

  1. When you’re ready to delete, send a DELETE request to /cam/v1/access-keys/{accessKeyUid}/versions/{version}.

  2. Use the path in the Location as a URL link in an additional GET request to see the key’s deploymentStatus. If you see PENDING_DELETION, Akamai is still processing the request. If you get a 404 - Resource not found message, you’ve successfully deleted that version.

Perform a property lookup request

Returns information about all of the Property Manager properties that use a specific version of an access key. This operation gets the data directly. To avoid any latency problems, run the Perform a property lookup request asynchronously operation.

GET /cam/v1/access-keys/{accessKeyUid}/versions/{version}/properties

Sample: /cam/v1/access-keys/12345/versions/2/properties

Parameter Type Sample Description
URL path parameters
accessKeyUid Integer 12345 The unique identifier Akamai assigns to an access key.
version Integer 2 The version number of the access key.

Status 200 application/json

Object type: Property

Download schema: properties.json

Response body:

{
    "properties": [
        {
            "propertyId": "prp_200073086",
            "propertyName": "sales.west",
            "productionVersion": 1,
            "stagingVersion": 1
        },
        {
            "propertyId": "prp_200073087",
            "propertyName": "sales.east",
            "productionVersion": null,
            "stagingVersion": 1
        }
    ]
}
  1. Run the List access keys operation and store the accessKeyUid for the relevant key.

  2. Run the List access key versions operation using the stored accessKeyUid.

  3. Locate the version you want and store its version.

  4. Make a GET request to /cam/v1/access-keys/{accessKeyUid}/versions/{version}/properties.

The operation responds with a Property object.

Get an ID for an asynchronous property lookup request

Get the unique identifier used to perform an asynchronous property lookup request.

GET /cam/v1/access-keys/{accessKeyUid}/versions/{version}/property-lookup-id

Sample: /cam/v1/access-keys/12345/versions/2/property-lookup-id

Parameter Type Sample Description
URL path parameters
accessKeyUid Integer 12345 The unique identifier Akamai assigns to an access key.
version Integer 2 The version number of the access key.

Status 202 application/json

Headers:

Location: /cam/v1/property-lookups/614949
Retry-After: 12

Object type: PropertyLookupId

Download schema: property-lookup-create-response.json

Response body:

{
    "lookupId": 614949,
    "retryAfter": 12
}
  1. Run the List access keys operation and store the accessKeyUid for the relevant key.

  2. Run the List access key versions operation.

  3. Locate the version you want and store its version.

  4. Make a GET request to /cam/v1/access-keys/{accessKeyUid}/versions/{version}/property-lookup-id.

  5. The operation responds with a PropertyLookupId object. Store the lookupId from the response to Perform a property lookup request asynchronously.

The response also includes these headers:

  • Location. Use this as a URL link directly in a GET request instead of using the separate operation to perform a property lookup request asynchronously.
  • Retry-After. This is the number of seconds you should wait before using the Location path in a GET request. This delay is in place to ensure you get accurate, up-to-date information.

Get the status of an access key job

Returns the current status and other details for a request to create a new access key.

GET /cam/v1/access-key-create-requests/{requestId}

Sample: /cam/v1/access-key-create-requests/1007

Parameter Type Sample Description
URL path parameters
requestId Integer 1007 The identifier assigned to a status request for an access key.

Status 200 application/json

Object type: AccessKeyStatus

Download schema: access-key-create-request-state.json

Response body:

{
    "requestId": 56546,
    "request": {
        "contractId": "1-7FALA",
        "groupId": 19715,
        "authenticationMethod": "AWS4_HMAC_SHA256",
        "accessKeyName": "Sales-s3",
        "networkConfiguration": {
            "additionalCdn": "RUSSIA_CDN",
            "securityNetwork": "ENHANCED_TLS"
        }
    },
    "processingStatus": "IN_PROGRESS",
    "requestedBy": "jdoe",
    "requestDate": "2021-02-26T13:34:36.715643Z",
    "accessKey": {
        "accessKeyUid": 12345,
        "link": "/cam/v1/access-keys/12345"
    },
    "accessKeyVersion": {
        "accessKeyUid": 12345,
        "version": 1,
        "link": "/cam/v1/access-keys/12345/versions/1"
    }
}
  1. Create a new access key.

  2. Store the requestId from the response.

  3. Make a GET request to /cam/v1/access-key-create-requests/{requestId}.

The operation responds with an AccessKeyStatus object.

Get the status of an access key version job

Returns the current status and other details for a request to create a new access key version.

GET /cam/v1/access-key-version-create-requests/{requestId}

Sample: /cam/v1/access-key-version-create-requests/7

Parameter Type Sample Description
URL path parameters
requestId Integer 7 The identifier assigned to a status request for an access key version.

Status 200 application/json

Object type: AccessKeyStatus

Download schema: access-key-create-request-state.json

Response body:

{
    "processingStatus": "IN_PROGRESS",
    "requestedBy": "jdoe",
    "requestDate": "2021-02-26T14:54:38.622074Z",
    "accessKeyVersion": {
        "accessKeyUid": 12345,
        "version": 2,
        "link": "/cam/v1/access-keys/12345/versions/2"
    }
}
  1. Create a new access key version.

  2. Store the requestId from the response.

  3. Make a GET request to /cam/v1/access-key-version-create-requests/{requestId}.

The operation responds with an AccessKeyVersionStatus object.

Perform a property lookup request asynchronously

Provides functionality similar to the Perform a property lookup request operation, but accesses the data asynchronously after running the Get an ID for an asynchronous property lookup request operation to obtain the lookupId.

GET /cam/v1/property-lookups/{lookupId}

Sample: /cam/v1/property-lookups/1

Parameter Type Sample Description
URL path parameters
lookupId Integer 1 The identifier of the property lookup.

Status 200 application/json

Object type: PropertyLookup

Download schema: property-lookup.json

Response body:

{
    "lookupId": 1221649,
    "lookupStatus": "COMPLETE",
    "properties": [
        {
            "propertyId": "prp_200073086",
            "propertyName": "sales.west",
            "productionVersion": 1,
            "stagingVersion": 1
        },
        {
            "propertyId": "prp_200073087",
            "propertyName": "sales.east",
            "productionVersion": null,
            "stagingVersion": 1
        }
    ]
}
  1. Run the Get an ID for an asynchronous property lookup request operation and store the lookupId value.

  2. Review the retryAfter object in the response and wait this number of seconds.

  3. Make a GET request to /cam/v1/property-lookups/{lookupId}.

The operation responds with a PropertyLookup object.

Data

This section describes the CAM API’s various data structures.

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.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

AccessKey

Detailed information about the access key.

Download schema: access-key.json, access-key-create-request.json

Sample GET response:

{
    "accessKeys": [
        {
            "accessKeyUid": 56514,
            "groups": [
                {
                    "groupId": 19715,
                    "groupName": "Sales",
                    "contractIds": [
                        "1-7FALA"
                    ]
                }
            ],
            "authenticationMethod": "AWS4_HMAC_SHA256",
            "accessKeyName": "Sales-s3",
            "note": "Sales key note",
            "creationDate": "2021-02-24T09:09:52.782555Z",
            "createdBy": "jdoe",
            "networkConfiguration": {
                "additionalCdn": "RUSSIA_CDN",
                "securityNetwork": "ENHANCED_TLS"
            },
            "latestVersion": 1
        },
        {
            "accessKeyUid": 56512,
            "groups": [
                {
                    "groupId": 176670,
                    "groupName": "Smarthomes",
                    "contractIds": [
                        "1-7FALA"
                    ]
                }
            ],
            "authenticationMethod": "AWS4_HMAC_SHA256",
            "accessKeyName": "Home automation | s3",
            "note": "Home automation key note",
            "creationDate": "2021-02-26T09:09:15.428314Z",
            "createdBy": "jdoe",
            "networkConfiguration": {
                "additionalCdn": null,
                "securityNetwork": "ENHANCED_TLS"
            },
            "latestVersion": 3
        }
    ]
}

AccessKey members

Member Type GET POST Description
AccessKey: Detailed information about the access key.
accessKeyName String The user defined in createdBy set this as the unique name for the access key.
accessKeyUid Integer Uniquely identifies the access key for use in keying resources within this API.
authenticationMethod Enumeration The type of signing process used to authenticate API requests: AWS4_HMAC_SHA256 for Amazon Web Services or GOOG4_HMAC_SHA256 for Google Cloud Services in interoperability mode.
contractId String The unique identifier for the contract assigned to the access key.
createdBy String The username of the person who created the access key.
createdTime String The time the access key was created, in ISO 8601 format.
credentials AccessKey.credentials The combination of a cloudAccessKeyId and a cloudSecretAccessKey used to sign API requests.
groupId Integer The unique identifier assigned to the access control group assigned to the access key.
groups AccessKey.groups[] A list of groups to which the access key is assigned.
latestVersion Integer The most recent version of the access key.
networkConfiguration AccessKey.networkConfiguration The API deploys the access key to this secure network.
note String, Null Further descriptive commentary.
AccessKey.credentials: The combination of a cloudAccessKeyId and a cloudSecretAccessKey used to sign API requests.
cloudAccessKeyId String A unique identifier that’s combined with the cloudSecretAccessKey to sign API requests. This is the access key ID (AWS) or access ID (GCS) you get from your cloud provider.
cloudSecretAccessKey String A value that’s combined with the cloudAccessKeyId to sign API requests. This is the secret access key (AWS) or secret (GCS) you get from your cloud provider.
AccessKey.groups[]: A list of groups to which the access key is assigned.
contractIds Array The Akamai contracts that are associated with this access key for the groupId.
groupId Integer Uniquely identifies the Akamai group that’s associated with the access key.
groupName String, Null The name of the group.
AccessKey.networkConfiguration: The API deploys the access key to this secure network.
additionalCdn Enumeration, Null You can deploy the access key to these additional networks. Use CHINA_CDN to make the access key available in Akamai’s China CDN. Use RUSSIA_CDN to make the access key available in Akamai’s Russia CDN. null indicates no CDN has been selected. If the securityNetwork is STANDARD_TLS, RUSSIA_CDN is included by default. If it’s ENHANCED_TLS, each network needs to be added manually to access these CDNs.
securityNetwork Enumeration The API deploys the access key to this secure network. STANDARD_TLS deploys the access key to Akamai’s standard secure network, which is non-PCI compliant. Enhanced TLS deploys the access key to Akamai’s enhanced secure network which is PCI compliant.

AccessKeyVersion

An outer wrapping object structure for a set of requested access key versions.

Download schema: access-key-versions.json, access-key-credentials.json

Sample GET response:

{
    "accessKeyVersions": [
        {
            "accessKeyUid": 12345,
            "versionGuid": "af434285-7841-11eb-817b-1f41209f67ec",
            "version": 2,
            "cloudAccessKeyId": null,
            "deploymentStatus": "PENDING_ACTIVATION",
            "createdBy": "jdoe",
            "creationDate": "2021-02-26T14:48:27.355346Z"
        },
        {
            "accessKeyUid": 12345,
            "versionGuid": "5f1c8194-7837-11eb-817b-1b3f28104c18",
            "version": 1,
            "cloudAccessKeyId": null,
            "deploymentStatus": "ACTIVE",
            "createdBy": "jdoe",
            "creationDate": "2021-02-26T13:34:37.916873Z"
        }
    ]
}

Sample POST body:

{
    "cloudAccessKeyId": "AKAMAICAMKEYID2EXAMPLE",
    "cloudSecretAccessKey": "cDdrcAMtrIAvN/h7dF/bAxLfiANAXAMPLEKEY"
}

AccessKeyVersion members

Member Type GET POST Description
AccessKeyVersion: An outer wrapping object structure for a set of requested access key versions.
accessKeyVersions AccessKeyVersion.accessKeyVersions[] The version of an access key.
cloudAccessKeyId String A unique identifier that’s combined with the cloudSecretAccessKey to sign API requests. This is the access key ID (AWS) or access ID (GCS) you get from your cloud provider.
cloudSecretAccessKey String A value that’s combined with the cloudAccessKeyId to sign API requests. This is the secret access key (AWS) or secret (GCS) you get from your cloud provider.
AccessKeyVersion.accessKeyVersions[]: The version of an access key.
accessKeyUid String Uniquely identifies the access key for use in keying resources within this API.
cloudAccessKeyId String The unique identifier assigned to the access key ID (AWS) or access ID (GCS).
createdBy String The username of the person who created this version of the access key.
createdTime String The time the access key version was created, in ISO 8601 format.
deploymentStatus Enumeration Status indicating whether the version has been activated to the Akamai networks. PENDING_ACTIVATION indicates that Akamai has received the request and a new version is in process. If ACTIVE, you can enable the version in the Origin Characteristics behavior when configuring your property to support CAM. Once an access key has been created, it’s available on both the staging and production Akamai networks. PENDING_DELETION indicates Akamai has received a request to delete the version and the system is processing it.
version Integer A positive integer identifying the incremental version.
versionGuid String The access key version’s universally unique identifier. Use this to identify the version within the Origin Characteristics behavior when configuring your property to support CAM.

AccessKeyStatus

Status information for requests to create an access key.

Download schema: access-key-create-request-state.json

Sample GET response:

{
    "requestId": 56546,
    "request": {
        "contractId": "1-7FALA",
        "groupId": 19715,
        "authenticationMethod": "AWS4_HMAC_SHA256",
        "accessKeyName": "Sales-s3",
        "networkConfiguration": {
            "additionalCdn": "RUSSIA_CDN",
            "securityNetwork": "ENHANCED_TLS"
        }
    },
    "processingStatus": "IN_PROGRESS",
    "requestedBy": "jdoe",
    "requestDate": "2021-02-26T13:34:36.715643Z",
    "accessKey": {
        "accessKeyUid": 12345,
        "link": "/cam/v1/access-keys/12345"
    },
    "accessKeyVersion": {
        "accessKeyUid": 12345,
        "version": 1,
        "link": "/cam/v1/access-keys/12345/versions/1"
    }
}

AccessKeyStatus members

Member Type Required Description
AccessKeyStatus: Status information for requests to create an access key.
accessKey AccessKeyStatus.accessKey Specific details for an access key. If the requested key hasn’t been created yet, this displays as null.
accessKeyVersion AccessKeyStatus.accessKeyVersion Specific details for a version of an access key.
processingStatus Enumeration The current status of a request to create a new access key. IN_PROGRESS for requests that are processing and DONE for complete. If a result of FAILED is shown, retry the create request and verify you’ve properly formatted the POST object.
request AccessKeyStatus.request Information about a request to create an access key.
requestDate String The time the access key create request was submitted, in ISO 8601 format.
requestedBy String The username of the person who submitted the request.
requestId Integer The unique identifier assigned to the access key request.
AccessKeyStatus.accessKey: Specific details for an access key. If the requested key hasn’t been created yet, this displays as null.
accessKeyUid Integer Uniquely identifies the access key for use in keying resources within this API.
link String An API hypermedia link to the access key associated with the request.
AccessKeyStatus.accessKeyVersion: Specific details for a version of an access key.
accessKeyUid Integer Uniquely identifies the access key for use in keying resources within this API.
link String An API hypermedia link to the version of the access key associated with the request.
version Integer The version of the access key.
AccessKeyStatus.request: Information about a request to create an access key.
accessKeyName String The user defined in createdBy set this as the unique name for the access key.
authenticationMethod Enumeration The type of signing process used to authenticate API requests: AWS4_HMAC_SHA256 for Amazon Web Services or GOOG4_HMAC_SHA256 for Google Cloud Services in interoperability mode.
contractId String Uniquely identifies the contract assigned when creating the access key.
groupId Integer Uniquely identifies the group assigned when creating the access key.
networkConfiguration AccessKeyStatus.request.networkConfiguration The API deploys the access key to this secure network.
AccessKeyStatus.request.networkConfiguration: The API deploys the access key to this secure network.
additionalCdn Enumeration, Null You can deploy the access key to these additional networks. Use CHINA_CDN to make the access key available in Akamai’s China CDN. Use RUSSIA_CDN to make the access key available in Akamai’s Russia CDN. null indicates no CDN has been selected. If the securityNetwork is STANDARD_TLS, RUSSIA_CDN is included by default. If it’s ENHANCED_TLS, each network needs to be added manually to access these CDNs.
securityNetwork Enumeration The API deploys the access key to this secure network. STANDARD_TLS deploys the access key to Akamai’s standard secure network, which is non-PCI compliant. Enhanced TLS deploys the access key to Akamai’s enhanced secure network which is PCI compliant.

AccessKeyVersionStatus

Status information for requests to create a new version of an access key.

Download schema: access-key-version-create-request-state.json

Sample GET response:

{
    "processingStatus": "IN_PROGRESS",
    "requestedBy": "jdoe",
    "requestDate": "2021-02-26T14:54:38.622074Z",
    "accessKeyVersion": {
        "accessKeyUid": 12345,
        "version": 2,
        "link": "/cam/v1/access-keys/12345/versions/2"
    }
}

AccessKeyVersionStatus members

Member Type Required Description
AccessKeyVersionStatus: Status information for requests to create a new version of an access key.
accessKeyVersion AccessKeyVersionStatus.accessKeyVersion{1} Specific details for a version of an access key. If the requested version of the key hasn’t been created yet, this displays as null.
processingStatus Enumeration The current status of a request to create a new version of an access key. IN_PROGRESS for requests that are processing and DONE for complete. If a result of FAILED is shown, retry the create request and verify you’ve properly formatted your POST object.
requestDate String The time the create request was submitted, in ISO 8601 format.
requestedBy String The username of the person who submitted the request.
AccessKeyVersionStatus.accessKeyVersion{1}: Specific details for a version of an access key. If the requested version of the key hasn’t been created yet, this displays as null.
accessKeyUid Integer Uniquely identifies the access key for use in keying resources within this API.
link String An API hypermedia link to the version of the access key associated with the request.
version Integer The version of the access key.

Property

Details on the Property Manager properties that use an access key.

Download schema: property-info.json

Sample GET response:

{
    "properties": [
        {
            "propertyId": "prp_200073086",
            "propertyName": "sales.west",
            "productionVersion": 1,
            "stagingVersion": 1
        },
        {
            "propertyId": "prp_200073087",
            "propertyName": "sales.east",
            "productionVersion": null,
            "stagingVersion": 1
        }
    ]
}

Property members

Member Type Required Description
Property: Details on the Property Manager properties that use an access key.
productionVersion Integer, Null Identifies the specific property version whose production status is either active or activating. Statuses include ACTIVE for versions that have been activated on production or NEW, PENDING, ZONE_1, ZONE_2, or ZONE_3 if not yet active. A null response indicates that the specified version of the property doesn’t exist.
propertyId String The unique identifier Akamai assigned to the matching property.
propertyName String Identifies the specific property name whose Origin Characteristics behavior uses the access key version.
stagingVersion Integer, Null Identifies the specific property version whose staging status is either active or activating. A null response indicates that the specified version of the property doesn’t exist.

PropertyLookupId

Asynchronous identifier information for a property lookup request. Used to generate an asynchronous request for a property lookup.

Download schema: property-lookup-create-response.json

Sample GET response:

{
    "lookupId": 614949,
    "retryAfter": 12
}

PropertyLookupId members

Member Type Required Description
PropertyLookupId: Asynchronous identifier information for a property lookup request. Used to generate an asynchronous request for a property lookup.
lookupId Integer Identifies each property lookup process.
retryAfter Integer The number of seconds you should wait before using the lookupId to check the status of a property lookup request.

PropertyLookup

The response to a request for an asynchronous property lookup job.

Download schema: property-lookup.json

Sample GET response:

{
    "lookupId": 1221649,
    "lookupStatus": "COMPLETE",
    "properties": [
        {
            "propertyId": "prp_200073086",
            "propertyName": "sales.west",
            "productionVersion": 1,
            "stagingVersion": 1
        },
        {
            "propertyId": "prp_200073087",
            "propertyName": "sales.east",
            "productionVersion": null,
            "stagingVersion": 1
        }
    ]
}

PropertyLookup members

Member Type Required Description
PropertyLookup: The response to a request for an asynchronous property lookup job.
lookupId Integer Identifies each property lookup process.
lookupStatus Enumeration The status of the property lookup process. COMPLETE indicates the lookup is finished and the response includes property-specific data. For ERROR, try the property lookup request again. GONE indicates the request has been lost. Try it again. IN_PROGRESS indicates that Akamai has received the lookup request and it’s being processed. PENDING indicates the request is in a queue to be processed.
properties PropertyLookup.properties[] Details on the Property Manager properties that use an access key.
PropertyLookup.properties[]: Details on the Property Manager properties that use an access key.
productionVersion Integer, Null Identifies the specific property version whose production status is either active or activating. Statuses include ACTIVE for versions that have been activated on production or NEW, PENDING, ZONE_1, ZONE_2, or ZONE_3 if not yet active. A null response indicates that the specified version of the property doesn’t exist.
propertyId String The unique identifier Akamai assigned to the matching property.
propertyName String Identifies the specific property name whose Origin Characteristics behavior uses the access key version.
stagingVersion Integer, Null Identifies the specific property version whose staging status is either active or activating. A null response indicates that the specified version of the property doesn’t exist.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

When the API encounters an error, it responds with an error code and an error message that provides details that can be useful for debugging.

This shows a typical error response when you try to access a non-existent accessKeyUid.

{
  "type": "resource not found",
  "title": "Resource Not Found",
  "instance": "c135eff0-43ec-4d0e-98c9-40efb5d19f35",
  "status": 404,
  "detail": "Access key with accessKeyUID '12346' doesn't exist.",
  "accessKeyUID": 12346
}

HTTP status codes

The API produces this set of HTTP status codes for both success and failure scenarios:

Code Description
200 The operation succeeded.
202 Request accepted, but not yet processed. With several operations in this API, data can’t be pre-cached and Akamai needs to assemble it. Some of these operations address data asynchronously.
400 Bad Request. This typically occurs due to a problem with the format of request data, such as an non-parsing or invalid body of data, or an invalid set of query parameters or values.
401 API authentication failure. See Get started for guidance on how to correctly set up your API hostname token.
403 No permission to access this resource. This most likely reflects a limitation on the identity of the Control Panel user corresponding to the API client. See Get started to make sure you have permission to access all the functionality you need.
404 Resource not found. This typically occurs when a resource keyed by a URL path parameter no longer exists, or if the request URL is garbled in some other way.
405 Method not supported. This typically occurs when the URL you’re calling responds to GET requests, but not PUT or DELETE.
409 Action not allowed at the time of the request. This can happen if you issue more than one request to perform the same action and the first one hasn’t completed.
415 Unsupported media type. This typically occurs when you request data in the wrong format, such as text/xml when the API can only exchange application/json data.
429 Too many requests. See Rate limiting for more information.
500 Internal server error.
501 Functionality not supported.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable. Akamai uses Rate limiting to enforce request limits.