Identity Management API v2

Manage your API client’s credentials and the credentials of other clients.

Learn more:


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 ADMINIdentity & 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 ADMINIdentity & 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.

Operation Method Endpoint
Get a client GET /identity-management/v2/api-clients/{clientId}
List credentials GET /identity-management/v2/api-clients/{clientId}/credentials{?actions}
Create a credential POST /identity-management/v2/api-clients/{clientId}/credentials
Get a credential GET /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}{?actions}
Update a credential PUT /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}
Remove a credential DELETE /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}
Deactivate credentials POST /identity-management/v2/api-clients/{clientId}/credentials/deactivate
Deactivate a credential POST /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}/deactivate
List account switch keys GET /identity-management/v2/api-clients/{clientId}/account-switch-keys{?search}
Get your client GET /identity-management/v2/api-clients/self
List your credentials GET /identity-management/v2/api-clients/self/credentials{?actions}
Create your credential POST /identity-management/v2/api-clients/self/credentials
Get your credential GET /identity-management/v2/api-clients/self/credentials/{credentialId}{?actions}
Update your credential PUT /identity-management/v2/api-clients/self/credentials/{credentialId}
Remove your credential DELETE /identity-management/v2/api-clients/self/credentials/{credentialId}
Deactivate your credentials POST /identity-management/v2/api-clients/self/credentials/deactivate
Deactivate your credential POST /identity-management/v2/api-clients/self/credentials/{credentialId}/deactivate
List your account switch keys GET /identity-management/v2/api-clients/self/account-switch-keys{?search}

Get a client

Returns details about a given API client.

GET /identity-management/v2/api-clients/{clientId}

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.

Status 200 application/json

Object type: Identity

Download schema: api-client.json

Response body:

{
    "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": []
                }
            ]
        }
    ]
}
  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Make a GET request to /identity-management/v2/api-clients/{clientId}.

  3. The operation responds with a Identity object.

List credentials

Returns all credentials for a given API client.

GET /identity-management/v2/api-clients/{clientId}/credentials{?actions}

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/credentials?actions=true

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Object type: Credential

Download schema: credentials.json

Response body:

[
    {
        "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"
    }
]
  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Optionally, set the actions query parameter to true if you want to include the client information in the response object.

  3. Make a GET request to /identity-management/v2/api-clients/{clientId}/credentials{?actions}.

  4. The operation responds with a Credential object.

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.

POST /identity-management/v2/api-clients/{clientId}/credentials

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/credentials

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.

Status 200 application/json

Object type: Credential

Download schema: credential.json

Response body:

{
    "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."
}
  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Make a POST request to /identity-management/v2/api-clients/{clientId}/credentials.

  3. The operation responds with a Credential object.

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.

GET /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}{?actions}

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/credentials/345678?actions=true

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.
credentialId Integer 345678 A credential’s unique identifier.
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Object type: Credential

Download schema: credential-nosecret.json

Response body:

{
    "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"
}
  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Run the List credentials operation and store the client’s credentialId.

  3. Optionally, set the actions query parameter to true if you want to include the client information in the response object.

  4. Make a GET request to /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}{?actions}.

  5. The operation responds with a Credential object.

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.

PUT /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/credentials/345678

Content-Type: application/json

Object type: Credential

Download schema: update-credential.json

Request body:

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}
Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.
credentialId Integer 345678 A credential’s unique identifier.

Status 200 application/json

Object type: Credential

Download schema: credential-nosecret.json

Response body:

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}
  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Run the List credentials operation and store the client’s credentialId.

  3. Run the Get a credential operation to get a Credential object.

  4. Modify the Credential object.

  5. PUT the object to /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}.

  6. The operation responds with a Credential object.

Remove a credential

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

DELETE /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/credentials/345678

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.
credentialId Integer 345678 A credential’s unique identifier.

Status 200

  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Run the List credentials operation and store the client’s credentialId.

  3. Make a DELETE request to /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}

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.

POST /identity-management/v2/api-clients/{clientId}/credentials/deactivate

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/credentials/deactivate

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.

Status 200

  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Make a POST request to /identity-management/v2/api-clients/{clientId}/credentials/deactivate.

Deactivate a credential

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

POST /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}/deactivate

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/credentials/345678/deactivate

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.
credentialId Integer 345678 A credential’s unique identifier.

Status 200

  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Run the List credentials operation and store the client’s credentialId.

  3. Make a POST request to /identity-management/v2/api-clients/{clientId}/credentials/{credentialId}/deactivate.

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.

GET /identity-management/v2/api-clients/{clientId}/account-switch-keys{?search}

Sample: /identity-management/v2/api-clients/pa444oyidwo6j4hy/account-switch-keys?search=1-2ABCD

Parameter Type Sample Description
URL path parameters
clientId String pa444oyidwo6j4hy A unique identifier for each API client.
Optional query parameters
search String 1-2ABCD Optionally filter results by accountId or accountName. Enter at least three characters in the string to filter the results.

Status 200 application/json

Object type: AccountSwitch

Download schema: account-switch-keys.json

Response body:

[
    {
        "accountName": "Rae Inc.",
        "accountSwitchKey": "1-EFGH"
    },
    {
        "accountName": "Doe_Indirect Customer",
        "accountSwitchKey": "1-ABCD:Z-XYZ"
    },
    {
        "accountName": "Doe_Direct Customer",
        "accountSwitchKey": "1-ABCD:Z-PQR"
    }
]
  1. If you don’t have the client’s clientId, use the instructions in Get started to locate it.

  2. Optionally, if you know the client’s account ID or account name, store at least three characters as the search parameter.

  3. Make a GET request to /identity-management/v2/api-clients/{clientId}/account-switch-keys{?search}.

  4. The operation responds with an AccountSwitch object.

Get your client

Returns details about your API client.

GET /identity-management/v2/api-clients/self

Status 200 application/json

Object type: Identity

Download schema: api-client.json

Response body:

{
    "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": []
                }
            ]
        }
    ]
}
  1. Make a GET request to /identity-management/v2/api-clients/self.

  2. The operation responds with a Identity object.

List your credentials

Returns a list of your API client’s credentials.

GET /identity-management/v2/api-clients/self/credentials{?actions}

Sample: /identity-management/v2/api-clients/self/credentials?actions=true

Parameter Type Sample Description
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Object type: Credential

Download schema: credentials.json

Response body:

[
    {
        "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"
    }
]
  1. Optionally, set the actions query parameter to true if you want to include the client information in the response object.

  2. Make a GET request to /identity-management/v2/api-clients/credentials{?actions}.

  3. The operation responds with a Credential object.

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.

POST /identity-management/v2/api-clients/self/credentials

Status 200 application/json

Object type: Credential

Download schema: credential.json

Response body:

{
    "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."
}
  1. Make a POST request to /identity-management/v2/api-clients/credentials.

  2. The operation responds with a Credential object.

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.

GET /identity-management/v2/api-clients/self/credentials/{credentialId}{?actions}

Sample: /identity-management/v2/api-clients/self/credentials/345678?actions=true

Parameter Type Sample Description
URL path parameters
credentialId Integer 345678 A credential’s unique identifier.
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Object type: Credential

Download schema: credential-nosecret.json

Response body:

{
    "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"
}
  1. Run the List credentials operation and store the client’s credentialId.

  2. Optionally, set the actions query parameter to true if you want to include the client information in the response object.

  3. Make a GET request to /identity-management/v2/api-clients/credentials/{credentialId}{?actions}.

  4. The operation responds with a Credential object.

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.

PUT /identity-management/v2/api-clients/self/credentials/{credentialId}

Sample: /identity-management/v2/api-clients/self/credentials/345678

Content-Type: application/json

Object type: Credential

Download schema: update-credential.json

Request body:

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}
Parameter Type Sample Description
URL path parameters
credentialId Integer 345678 A credential’s unique identifier.

Status 200 application/json

Object type: Credential

Download schema: credential-nosecret.json

Response body:

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}
  1. Run the List credentials operation and store the client’s credentialId.

  2. Run the Get a credential operation to get a Credential object.

  3. Modify the Credential object.

  4. PUT the object to /identity-management/v2/api-clients/self/credentials/{credentialId}.

  5. The operation responds with a Credential object.

Remove your credential

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

DELETE /identity-management/v2/api-clients/self/credentials/{credentialId}

Sample: /identity-management/v2/api-clients/self/credentials/345678

Parameter Type Sample Description
URL path parameters
credentialId Integer 345678 A credential’s unique identifier.

Status 200

  1. Run the List credentials operation and store the client’s credentialId.

  2. Make a DELETE request to /identity-management/v2/api-clients/credentials/{credentialId}.

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.

POST /identity-management/v2/api-clients/self/credentials/deactivate

Status 200

  1. Run the List credentials operation and store the client’s credentialId.

  2. Make a POST request to /identity-management/v2/api-clients/credentials/deactivate.

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.

POST /identity-management/v2/api-clients/self/credentials/{credentialId}/deactivate

Sample: /identity-management/v2/api-clients/self/credentials/345678/deactivate

Parameter Type Sample Description
URL path parameters
credentialId Integer 345678 A credential’s unique identifier.

Status 200

  1. Run the List credentials operation and store the client’s credentialId.

  2. Make a POST request to /identity-management/v2/api-clients/credentials/{credentialId}/deactivate.

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.

GET /identity-management/v2/api-clients/self/account-switch-keys{?search}

Sample: /identity-management/v2/api-clients/self/account-switch-keys?search=1-2ABCD

Parameter Type Sample Description
Optional query parameters
search String 1-2ABCD Optionally filter results by accountId or accountName. Enter at least three characters in the string to filter the results.

Status 200 application/json

Object type: AccountSwitch

Download schema: account-switch-keys.json

Response body:

[
    {
        "accountName": "Rae Inc.",
        "accountSwitchKey": "1-EFGH"
    },
    {
        "accountName": "Doe_Indirect Customer",
        "accountSwitchKey": "1-ABCD:Z-XYZ"
    },
    {
        "accountName": "Doe_Direct Customer",
        "accountSwitchKey": "1-ABCD:Z-PQR"
    }
]
  1. Optionally, if you know your client’s account ID or account name, store at least three characters as the search parameter.

  2. Make a GET request to /identity-management/v2/api-clients/account-switch-keys{?search}.

  3. The operation responds with a AccountSwitch object.

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:

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.

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

Member Type Required Description
Credential: This object encapsulates all members for the credential data structure.
clientSecret String Read-only. The client secret.
clientToken String Identifies your client.
createdOn String Read-only. The date the credential was made.
credentialId Integer Read-only. Uniquely identifies each credential.
description String Lets you add your own notes or description for your credential.
expiresOn String The date the credential no longer provides access. The default expiration date is 2 years from the creation date.
status Enumeration Shows whether a credential is ACTIVE, INACTIVE, or DELETED. You can switch a credential’s status between ACTIVE and INACTIVE. Note that once you change the status to DELETED, you’ve actually deleted it and it can’t be reactivated.

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

Member Type Description
Identity: This object encapsulates the response schema for creating API client.
accessToken String Part of the client secret that identifies your API client and lets you access applications and resources. Tokens are unique per client.
actions Identity.actions Encapsulates actions the API client may perform.
activeCredentialCount Integer Number of credentials active for the API client.
allAccessibleApis Boolean When enabled, grants the client access to all available APIs. Otherwise access is limited to the specified set of apis.
allowAccountSwitch Boolean If you can use the API client to manage more than one account.
apis Identity.apis[] Lists APIs you’d like to use. It’s a specific set of accessible APIs only when allAccessibleApis is disabled.
baseUrl String The base URL for the service.
ccuParams Identity.ccuParams Additional data needed to configure the client for access to CCU API in apis.
clientDescription String Description of the API client.
clientId String Unique identifier for an API client.
clientName String The API client’s human-readable name.
createdBy String The user who created the API client.
createdDate String Read-only. An ISO 8601 timestamp indicating when the API client was created.
credentials Identity.credentials[] Details of a credential.
groups Identity.groups[] The groups an API client can access.
locked Boolean When enabled, you can lock the client to prevent anyone from using it to access services on Control Center.
notificationList Array List of email addresses to notify of any expiring credentials.
serviceProviderId Integer A unique identifier for a service provider.
uiIdentityId String The unique identifier of the user the API client is being created for.
uiUserName String The human-readable username of the person who owns the API client.
useOwnerGroups Boolean When enabled, grants the client the same group access as the owner. Otherwise access is limited to the groups specified in groups.
Identity.actions: Encapsulates actions the API client may perform.
deactivateAll Boolean When enabled, all credentials of the API client can be deactivated.
delete Boolean When enabled, the API client can be deleted.
edit Boolean When enabled, the API client can be updated.
editApis Boolean When enabled, the apis of the API client can be updated.
editAuth Boolean When enabled, the groups or apis of the API client can be updated.
editGroups Boolean When enabled, the groups of the API client can be updated.
editSwitchAccount Boolean When enabled, the API client option to manage many accounts can be updated.
lock Boolean When enabled, the API client can be locked if it’s currently unlocked.
transfer Boolean When enabled, the API client can be transferred to a new owner.
unlock String When enabled, the API client can be unlocked if it’s currently locked.
Identity.apis[]: Lists APIs you’d like to use. It’s a specific set of accessible APIs only when allAccessibleApis is disabled.
apiId Integer A unique identifier for each API.
apiName String The name of a API, like Diagnostic Tools, or Identity Management: API.
description String Description of the API.
documentationUrl String Link to more information about the API.
endPoint String The endpoint to access a API.
grantScope String The level of access you give to an API client on a per API basis.
Identity.ccuParams: Additional data needed to configure the client for access to CCU API in apis.
purgeByCacheTag Boolean When enabled, the API client can purge content by cache tag.
purgeByCpcode Boolean When enabled, the API client can purge content by CP code.
purgeCpcodes Array Lists all CP codes that your API client is allowed to purge.
Identity.credentials[]: Details of a credential.
actions Identity.credentials[].actions Encapsulates the different ways you can edit an API client, including changing its owner, accessing rights to Control Center, or deleting it.
clientToken String Token generated for the credential to be used.
createdOn String Read-only. An ISO 8601 timestamp indicating when the credential was created.
credentialId String A unique identifier for a credential.
description String A descriptive label for the client.
expiresOn String An ISO 8601 timestamp indicating when the credential expires.
status Enumeration Indicates whether the credential can be used. ACTIVE means the credential can be used. INACTIVE means the credential isn’t active and can’t be used, and DELETED means the credential no longer exists.
Identity.credentials[].actions: Encapsulates the different ways you can edit an API client, including changing its owner, accessing rights to Control Center, or deleting it.
activate Boolean When enabled, the credential can be activated.
deactivate Boolean When enabled, the credential can be deactivated.
delete Boolean When enabled, the credential can be deleted.
editDescription String When enabled, credential’s description can be edited.
editExpiration Boolean When enabled, credential’s expiration date can be updated.
Identity.groups[]: The groups an API client can access.
groupId Integer The group’s unique identifier.
groupName String The human-readable name for a group.
isBlocked Boolean If true, the API client has access to the group’s parent, but can’t access the child group.
parentGroupId String The unique identifier for the parent group within the group tree. If you’re viewing group info for a root-level group, you may not see this member.
roleDescription String The human-readable description for a role.
roleId Integer A role’s unique identifier.
roleName String The human-readable name for a role.
subGroups Identity.groups[] Children of the parent group, represented as an array of Identity.groups[] objects. Permissions cascade downward from parent to child unless the child group’s isBlocked is true.

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

Member Type Description
AccountSwitch: This object encapsulates a collection of contexts the client can manage.
accountName String The name you supply for an account.
accountSwitchKey String The identifier for an account other than your API client’s default.

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:

Code Description
200 The operation was successful.
201 The resource was created successfully.
401 API authentication failure. See Get started for guidance on how to correctly set up your API hostname token.
402 Failed request.
403 The client isn’t authorized to invoke the service. See Get started for information on API authorization.
404 Couldn’t find the requested resource.
405 The specified HTTP method isn’t supported for this resource.
415 Returned when the server can’t generate an acceptable response by the client.
500 The platform encountered an unknown error when trying to create the resource.
503 The service is temporarily unavailable.