Learn more:

• Identity and Access Management

• Identity Management: User Administration API

• Download this API’s RAML and JSON schema descriptors.

Overview

The Identity Management API lets you manage API credentials for your API client and other API clients based on your group roles and permissions. If you’re a user or administrator, use this API to programmatically manage API access availability and run all production settings.

In the previous version of the API, you could only manage your own client’s credentials. This version lets you manage your client’s credentials and the credentials of other API clients.

Get started

Before using this API for the first time:

• If you want to manage API credentials and you don’t have an API client, create one in the Identity and Access Management application:

  1. Launch the Identity and Access Management application in Akamai Control Center.

  2. In Control Center, click ≡ ⇒ ACCOUNT ADMIN ⇒ Identity & access, then click New API client for me.

  3. Under Select API option, click Quick to instantly create an API client and a credential for the Akamai APIs you can access. This client’s API access levels, group roles, and permissions are identical to yours.

• If you want to manage API credentials for a specific API client rather than the client you’re currently using, you need that client’s clientId:

  1. Launch the Identity and Access Management application in Akamai Control Center.

  2. In Control Center, click ≡ ⇒ ACCOUNT ADMIN ⇒ Identity & access.

  3. On the Users and API Clients tab, under Client Name, select the API client you want to manage.

  4. Under Details, click Show additional details.

  5. Use the API client’s ID as the clientId value in each operation where applicable.

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

API Concepts

The Identity Management API assigns a variety of access and permission values that grant or restrict access to specified applications. When using this API, you need to be familiar with these concepts:

• API client. A set of tokens that provides users with access to specific APIs.

• Owner. A user or automation that uses a specific API client for API access. API clients are reassignable. However, only the API client owner may update a client’s credentials.

• API. The specific Control Center API you want to use with your API client like the Property Manager API (PAPI) or the Diagnostic tools API.

Rotate credentials

To rotate your API client’s credentials or another client’s credentials, modify a pair of individual credential members.

Rotate credentials for your API client:

1. Run Update your credential to update the expiration date of an old credential to a new date you choose to let it auto-expire.

2. Run Create your credential so the new credential can replace the old one.

3. Deploy your new keys and secrets.

Rotate credentials for a given API client:

1. Run Update a credential to update the expiration date of an old credential to a new date you choose to let it auto-expire.

2. Run Create a credential so the new credential can replace the old one.

3. Deploy your new keys and secrets.

You should leave enough overlap between the old and new credentials to ensure you maintain access during the rotation. If your old credentials expire before you finish updating the new ones, you’ll lose access to the APIs assigned to the expired credentials.

Resources

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

API summary

Download the RAML descriptors for this API.

Get a client

Returns details about a given API client.

{
    "clientId": "nmchqgmuigems5g4",
    "clientName": "Client Name",
    "clientDescription": "reporting client",
    "uiUserName": "johnDoe",
    "uiIdentityId": "1-abcd",
    "activeCredentialCount": 1,
    "createdDate": "2016-02-24T22:43:12.000Z",
    "createdBy": "jakeDoe",
    "locked": false,
    "useOwnerGroups": false,
    "allAccessibleApis": false,
    "allowAccountSwitch": false,
    "serviceProviderId": 1,
    "baseURL": "https://akaa-ylebtkmgfpnm5p4y-syw7bxjr2y4fgo5q.luna.akamaiapis.net/",
    "accessToken": "akab-xokhgtv6kebvuctv-q2iopin6rtw68875",
    "notificationList": [
        "john.doe@example.com"
    ],
    "actions": {
        "editGroups": true,
        "editApis": true,
        "lock": true,
        "unlock": false,
        "editAuth": true,
        "edit": true,
        "editSwitchAccount": false,
        "transfer": true,
        "delete": false,
        "deactivateAll": true
    },
    "ccuParams": {
        "purgeByCpcode": false,
        "purgeByCacheTag": false,
        "purgeCpcodes": [
            461295,
            461145
        ]
    },
    "apis": [
        {
            "apiId": 3105,
            "apiName": "Adaptive Acceleration",
            "description": "Adaptive Acceleration",
            "endPoint": "/adaptive-acceleration",
            "documentationUrl": "https://developer.akamai.com/api/core_features/adaptive_acceleration/v1.html",
            "grantScope": "READ-WRITE"
        }
    ],
    "credentials": [
        {
            "credentialId": 123456,
            "clientToken": "client-token-for-cred",
            "status": "ACTIVE",
            "createdOn": "2016-02-24T22:43:12.000Z",
            "description": "reporting client",
            "expiresOn": "2017-02-24T22:43:12.000Z",
            "keyAlias": "100",
            "clientId": 9876,
            "actions": {
                "deactivate": true,
                "delete": false,
                "activate": false,
                "editDescription": true,
                "editExpiration": true
            }
        }
    ],
    "groups": [
        {
            "groupId": 18385,
            "roleId": 14,
            "isBlocked": false,
            "subGroups": [
                {
                    "groupId": 18436,
                    "roleId": null,
                    "isBlocked": false,
                    "subGroups": []
                }
            ]
        }
    ]
}

List credentials

Returns all credentials for a given API client.

[
    {
        "credentialId": 99999,
        "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkfnanv",
        "createdOn": "2016-11-01T23:06:59.000Z",
        "expiresOn": "2018-11-01T23:06:59.000Z",
        "status": "ACTIVE",
        "description": "John's access to Property Manager"
    },
    {
        "credentialId": 88888,
        "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkouoiuo",
        "createdOn": "2016-11-01T23:06:59.000Z",
        "expiresOn": "2018-11-01T23:06:59.000Z",
        "status": "INACTIVE",
        "description": "John's access to Event Center"
    }
]

Create a credential

Creates a new credential for a given API client. Only the client’s owner may create credentials for the client. Credentials are in active status at creation. They expire two years from their creation date. However, when the API client’s permissions are based on Control Center permissions, credentials expire differently and follow the same rotation schedule listed for user passwords on those accounts. Run the Update a credential operation to change the expiration date, description, or status. Save the values from the response, such as the credentialID, for future use. This is the only time you’ll see the client secret. Save the credential at this time to avoid the need to create a new one.

{
    "credentialId": 14111,
    "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkfnanv",
    "clientSecret": "aasd3adHRjBfroGqYC/rc/jDaZTZxssdaa/YjD6uA=",
    "createdOn": "2016-11-01T23:06:59.000Z",
    "expiresOn": "2018-11-01T23:06:59.000Z",
    "status": "ACTIVE",
    "description": "New credential for John."
}

Get a credential

Returns details of a specific credential for a given API client. To change the credential’s expiration date or toggle its activation status, run the Update credential for an API client operation.

{
    "credentialId": 99999,
    "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkfnanv",
    "status": "ACTIVE",
    "createdOn": "2016-11-01T23:06:59.000Z",
    "description": "Credential with no secret",
    "expiresOn": "2018-11-01T23:06:59.000Z"
}

Update a credential

Updates the details of a specific credential for a given API client. You can change the expiration date, description, or toggle the activation status. This isn’t the same as rotating a credential. For details, see Rotate credentials.

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}

Remove a credential

Deletes a specific credential from a given API client. You can only delete inactive credentials.

Deactivate credentials

Deactivates all credentials for a given API client. This doesn’t delete the API client or the credentials. To deactivate a single credential, run the Update a credential operation and set the status to INACTIVE.

Deactivate a credential

Deactivates a specific credential for a given API client. This doesn’t delete the API client or the other credentials.

List account switch keys

The response object contains the accountSwitchKeys and accountNames you can access based on the permissions of the client. Once you have the accountSwitchKeys, you can make an API call to another account.

[
    {
        "accountName": "Rae Inc.",
        "accountSwitchKey": "1-EFGH"
    },
    {
        "accountName": "Doe_Indirect Customer",
        "accountSwitchKey": "1-ABCD:Z-XYZ"
    },
    {
        "accountName": "Doe_Direct Customer",
        "accountSwitchKey": "1-ABCD:Z-PQR"
    }
]

Get your client

Returns details about your API client.

{
    "clientId": "nmchqgmuigems5g4",
    "clientName": "Client Name",
    "clientDescription": "reporting client",
    "uiUserName": "johnDoe",
    "uiIdentityId": "1-abcd",
    "activeCredentialCount": 1,
    "createdDate": "2016-02-24T22:43:12.000Z",
    "createdBy": "jakeDoe",
    "locked": false,
    "useOwnerGroups": false,
    "allAccessibleApis": false,
    "allowAccountSwitch": false,
    "serviceProviderId": 1,
    "baseURL": "https://akaa-ylebtkmgfpnm5p4y-syw7bxjr2y4fgo5q.luna.akamaiapis.net/",
    "accessToken": "akab-xokhgtv6kebvuctv-q2iopin6rtw68875",
    "notificationList": [
        "john.doe@example.com"
    ],
    "actions": {
        "editGroups": true,
        "editApis": true,
        "lock": true,
        "unlock": false,
        "editAuth": true,
        "edit": true,
        "editSwitchAccount": false,
        "transfer": true,
        "delete": false,
        "deactivateAll": true
    },
    "ccuParams": {
        "purgeByCpcode": false,
        "purgeByCacheTag": false,
        "purgeCpcodes": [
            461295,
            461145
        ]
    },
    "apis": [
        {
            "apiId": 3105,
            "apiName": "Adaptive Acceleration",
            "description": "Adaptive Acceleration",
            "endPoint": "/adaptive-acceleration",
            "documentationUrl": "https://developer.akamai.com/api/core_features/adaptive_acceleration/v1.html",
            "grantScope": "READ-WRITE"
        }
    ],
    "credentials": [
        {
            "credentialId": 123456,
            "clientToken": "client-token-for-cred",
            "status": "ACTIVE",
            "createdOn": "2016-02-24T22:43:12.000Z",
            "description": "reporting client",
            "expiresOn": "2017-02-24T22:43:12.000Z",
            "keyAlias": "100",
            "clientId": 9876,
            "actions": {
                "deactivate": true,
                "delete": false,
                "activate": false,
                "editDescription": true,
                "editExpiration": true
            }
        }
    ],
    "groups": [
        {
            "groupId": 18385,
            "roleId": 14,
            "isBlocked": false,
            "subGroups": [
                {
                    "groupId": 18436,
                    "roleId": null,
                    "isBlocked": false,
                    "subGroups": []
                }
            ]
        }
    ]
}

List your credentials

Returns a list of your API client’s credentials.

[
    {
        "credentialId": 99999,
        "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkfnanv",
        "createdOn": "2016-11-01T23:06:59.000Z",
        "expiresOn": "2018-11-01T23:06:59.000Z",
        "status": "ACTIVE",
        "description": "John's access to Property Manager"
    },
    {
        "credentialId": 88888,
        "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkouoiuo",
        "createdOn": "2016-11-01T23:06:59.000Z",
        "expiresOn": "2018-11-01T23:06:59.000Z",
        "status": "INACTIVE",
        "description": "John's access to Event Center"
    }
]

Create your credential

Creates a new credential for your API client. Only you may create credentials for this client. Credentials are in active status at creation. They expire two years from their creation date. However, when the API client’s permissions are based on Control Center permissions, credentials expire differently and follow the same rotation schedule listed for user passwords on those accounts. Run the Update a credential operation to change the expiration date, description, or status. Save the values from the response, such as the credentialID for future use. This is the only time you’ll see the client secret. Save the credential at this time to avoid the need to create a new one.

{
    "credentialId": 14111,
    "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkfnanv",
    "clientSecret": "aasd3adHRjBfroGqYC/rc/jDaZTZxssdaa/YjD6uA=",
    "createdOn": "2016-11-01T23:06:59.000Z",
    "expiresOn": "2018-11-01T23:06:59.000Z",
    "status": "ACTIVE",
    "description": "New credential for John."
}

Get your credential

Returns details of a specific credential for your API client. To change the credential’s expiration date or toggle its activation status, run the Update a credential operation.

{
    "credentialId": 99999,
    "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkfnanv",
    "status": "ACTIVE",
    "createdOn": "2016-11-01T23:06:59.000Z",
    "description": "Credential with no secret",
    "expiresOn": "2018-11-01T23:06:59.000Z"
}

Update your credential

Updates the details of a specific credential for your API client. You can change the expiration date, description, or toggle the activation status. This isn’t the same as rotating a credential. For details, see Rotate credentials.

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}

Remove your credential

Deletes a specific credential from your API client. You can only delete inactive credentials.

Deactivate your credentials

Deactivates all credentials for your API client. This doesn’t delete the API client or the credentials. To deactivate a single credential, use the Update your credential operation and set the status to INACTIVE.

Deactivate your credential

Deactivates a specific credential for your API client. This doesn’t delete the client or the credentials. To update a specific credential, run the Update your credential operation.

List your account switch keys

The response object contains the accountSwitchKeys and account names you can access based on the permissions of your API client. Once you have the accountSwitchKeys, you can make an API call to another account.

[
    {
        "accountName": "Rae Inc.",
        "accountSwitchKey": "1-EFGH"
    },
    {
        "accountName": "Doe_Indirect Customer",
        "accountSwitchKey": "1-ABCD:Z-XYZ"
    },
    {
        "accountName": "Doe_Direct Customer",
        "accountSwitchKey": "1-ABCD:Z-PQR"
    }
]

Data

This section describes the API’s various data structures.

Download the JSON schemas for this API.

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

Credential

This object encapsulates all members for the credential data structure.

Download schema: credential.json

Sample GET:

{
    "credentialId": 99999,
    "clientToken": "akaa-abcdakjsdkfnanva-abcdakjsdkfnanv",
    "status": "ACTIVE",
    "createdOn": "2016-11-01T23:06:59.000Z",
    "description": "Credential with no secret",
    "expiresOn": "2018-11-01T23:06:59.000Z"
}

Credential members

Identity

This object encapsulates the response schema for creating API client.

Download schema: api-client.json

Sample GET:

{
    "clientId": "nmchqgmuigems5g4",
    "clientName": "Client Name",
    "clientDescription": "reporting client",
    "uiUserName": "johnDoe",
    "uiIdentityId": "1-abcd",
    "activeCredentialCount": 1,
    "createdDate": "2016-02-24T22:43:12.000Z",
    "createdBy": "jakeDoe",
    "locked": false,
    "useOwnerGroups": false,
    "allAccessibleApis": false,
    "allowAccountSwitch": false,
    "serviceProviderId": 1,
    "baseURL": "https://akaa-ylebtkmgfpnm5p4y-syw7bxjr2y4fgo5q.luna.akamaiapis.net/",
    "accessToken": "akab-xokhgtv6kebvuctv-q2iopin6rtw68875",
    "notificationList": [
        "john.doe@example.com"
    ],
    "actions": {
        "editGroups": true,
        "editApis": true,
        "lock": true,
        "unlock": false,
        "editAuth": true,
        "edit": true,
        "editSwitchAccount": false,
        "transfer": true,
        "delete": false,
        "deactivateAll": true
    },
    "ccuParams": {
        "purgeByCpcode": false,
        "purgeByCacheTag": false,
        "purgeCpcodes": [
            461295,
            461145
        ]
    },
    "apis": [
        {
            "apiId": 3105,
            "apiName": "Adaptive Acceleration",
            "description": "Adaptive Acceleration",
            "endPoint": "/adaptive-acceleration",
            "documentationUrl": "https://developer.akamai.com/api/core_features/adaptive_acceleration/v1.html",
            "grantScope": "READ-WRITE"
        }
    ],
    "credentials": [
        {
            "credentialId": 123456,
            "clientToken": "client-token-for-cred",
            "status": "ACTIVE",
            "createdOn": "2016-02-24T22:43:12.000Z",
            "description": "reporting client",
            "expiresOn": "2017-02-24T22:43:12.000Z",
            "keyAlias": "100",
            "clientId": 9876,
            "actions": {
                "deactivate": true,
                "delete": false,
                "activate": false,
                "editDescription": true,
                "editExpiration": true
            }
        }
    ],
    "groups": [
        {
            "groupId": 18385,
            "roleId": 14,
            "isBlocked": false,
            "subGroups": [
                {
                    "groupId": 18436,
                    "roleId": null,
                    "isBlocked": false,
                    "subGroups": []
                }
            ]
        }
    ]
}

Identity members

AccountSwitch

This object encapsulates a collection of contexts the client can manage.

Download schema: account-switch-keys.json

Sample GET response:

[
    {
        "accountName": "Rae Inc.",
        "accountSwitchKey": "1-EFGH"
    },
    {
        "accountName": "Doe_Indirect Customer",
        "accountSwitchKey": "1-ABCD:Z-XYZ"
    },
    {
        "accountName": "Doe_Direct Customer",
        "accountSwitchKey": "1-ABCD:Z-PQR"
    }
]

AccountSwitch members

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

The Identity Management API responds with HTTP problem error objects that provide details useful for debugging.

This example shows a typical error response. The outer object characterizes the overall problem, while the details array lists potentially more than one problem detected in the request.

{
    "type" : "/identity-management/error-types/3",
    "status" : 403,
    "title" : "no access",
    "instance" : "",
    "errors" : [ ],
    "detail" : ""
}

HTTP status codes

This table lists the range of HTTP response codes the API may produce for both success and error cases: