Identity Management API v1

Manage your credentials, rotate credentials, and retrieve credential information.

Learn more:


Overview

The Identity Management API allows you to manage your credentials. Use this API to rotate credentials and retrieve credential information.

Who should use this API

Use this API if you are a user or administrator who wants to programmatically manage API access availability. Additionally, use this API if you run all production settings.

Getting started

To configure this API for the first time:

  • If you do not already have an API client, create one in Luna through the Manage APIs app.

  • This API requires an openIdentityId. The openIdentityId is visible in the credential details section of the OPEN Identity details page. To retrieve the ID:

    1. In Luna, Navigate to the API Client detail page.

    2. Retrieve the ID from underneath API Client name.

    3. Insert the ID 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.

  • To enable this API, choose the API service named Identity Management: API, and set the access level to READ-WRITE.

Concepts

The Identity Management API assigns a variety of access and permission values, ultimately granting or restricting access to specified applications.

  • OPEN Identity. Also known as the API client. A set of permissions and tokens providing a user with access to specific APIs.

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

  • Service or API Service. The API you want to use with your client. Examples include the Property Manager API (PAPI), or the Diagnostic tools API.

Rotate credentials

This API allows you to rotate your credentials by modifying a pair of individual credentials. To rotate credentials:

  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 will lose access to the APIs associated with the expired credentials.

Resources

This API requires an openIdentityId. The openIdentityId is visible in the credential details section of the OPEN Identity details page. To retrieve the ID:

  1. In Luna, navigate to the API client detail page.

  2. Retrieve the ID from underneath API Client name.

  3. Insert the ID in each operation where applicable.

Alternatively, you can call the Get an access token method to retrieve the openIdentityId.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List credentials GET /identity-management/v1/open-identities/{openIdentityId}/credentials{?actions}
Create a credential POST /identity-management/v1/open-identities/{openIdentityId}/credentials
Get a credential GET /identity-management/v1/open-identities/{openIdentityId}/credentials/{credentialId}{?actions}
Update a credential PUT /identity-management/v1/open-identities/{openIdentityId}/credentials/{credentialId}
Remove a credential DELETE /identity-management/v1/open-identities/{openIdentityId}/credentials/{credentialId}
Deactivate all credentials POST /identity-management/v1/open-identities/{openIdentityId}/credentials/deactivate
List account switch keys GET /identity-management/v1/open-identities/{openIdentityId}/account-switch-keys{?search}
Get a client by its access token GET /identity-management/v1/open-identities/tokens/{accessToken}{?actions}

List credentials

Get an API client’s credentials.

GET /identity-management/v1/open-identities/{openIdentityId}/credentials{?actions}

Sample: /identity-management/v1/open-identities/pa444oyidwo6j4hy/credentials?actions=true

Parameter Type Sample Description
URL parameters
openIdentityId 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

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. Retrieve identityID using the instructions in Getting started.

  2. Make a GET request to /identity-management/v1/open-identities/{openIdentityId}/credentials.

Create a credential

Create a new credential for an API client. Only the owner of an identity can create credentials for it. Credentials are in active status at creation, and by default expire two years from their creation date. However, credentials expire differently when the API client is based on Luna user permissions, 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 information from the response information like the credentialID for future use. This is the only time you will see the client secret. If you do not save it at this time, you will need to create a new credential.

POST /identity-management/v1/open-identities/{openIdentityId}/credentials

Sample: /identity-management/v1/open-identities/pa444oyidwo6j4hy/credentials

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

Status 200 application/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 already have an identityId, get one as described in Getting started.

  2. Make a POST request to /identity-management/v1/open-identities/{openIdentityId}/credentials.

Get a credential

Get details for a single credential. Use Update a credential to change the credential’s expiration date, or toggle the credential’s activation status.

GET /identity-management/v1/open-identities/{openIdentityId}/credentials/{credentialId}{?actions}

Sample: /identity-management/v1/open-identities/pa444oyidwo6j4hy/credentials/345678?actions=true

Parameter Type Sample Description
URL parameters
openIdentityId 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

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 already have an identityId, get one as described in Getting started.

  2. Use List credentials to retrieve a specific credentialId.

  3. Make a GET request to /identity-management/v1/open-identities/{openIdentityId}/credential/{credentialId}.

Update a credential

Edit credential details. You can change the expiration date, description, or toggle the activation status. This is not the same as rotating a credential. For credential rotation, see Rotate credentials.

PUT /identity-management/v1/open-identities/{openIdentityId}/credentials/{credentialId}

Sample: /identity-management/v1/open-identities/pa444oyidwo6j4hy/credentials/345678

Content-Type: application/json

Request Body:

{
    "status": "ACTIVE",
    "expiresOn": "2018-02-24T22:43:12Z",
    "description": "John's access to Luna."
}
Parameter Type Sample Description
URL parameters
openIdentityId String pa444oyidwo6j4hy A unique identifier for each API client.
credentialId Integer 345678 A credential’s unique identifier.

Status 200 application/json

Response Body:

{
    "status": "ACTIVE",
    "expiresOn": "2018-10-11T23:06:59.000Z",
    "description": "Update this credential"
}
  1. If you don’t already have an identityId, get one as described in Getting started.

  2. Use List credentials to retrieve a specific credentialId.

  3. Run Get a credential to get a Credential object for the next step.

  4. Modify the Credential object.

  5. PUT the object to /identity-management/v1/open-identities/{openIdentityId}/credential/{credentialId}.

Remove a credential

Delete a credential. You can only delete inactive credentials.

DELETE /identity-management/v1/open-identities/{openIdentityId}/credentials/{credentialId}

Sample: /identity-management/v1/open-identities/pa444oyidwo6j4hy/credentials/345678

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

Status 200

  1. If you don’t already have an identityId, get one as described in Getting started.

  2. Use List credentials to retrieve a specific credentialId.

  3. Make a DELETE request to /identity-management/v1/open-identities/{openIdentityId}/credential/{credentialId}.

Deactivate all credentials

Deactivate all credentials for an API client. This does not delete the OPEN identity or the credentials. To deactivate a single credential, run the Update a credential operation and set the status to INACTIVE.

POST /identity-management/v1/open-identities/{openIdentityId}/credentials/deactivate

Sample: /identity-management/v1/open-identities/pa444oyidwo6j4hy/credentials/deactivate

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

Status 200

  1. If you don’t already have identityId, get one as described in Getting started.

  2. Make a POST request to /identity-management/v1/open-identities/{openIdentityId}/credentials/deactivate.

List 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 need, you can make an API call to another account.

GET /identity-management/v1/open-identities/{openIdentityId}/account-switch-keys{?search}

Sample: /identity-management/v1/open-identities/pa444oyidwo6j4hy/account-switch-keys?search=1-2ABCD

Parameter Type Sample Description
URL parameters
openIdentityId 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

Response Body:

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

Get a client by its access token

View an API client’s details. This operation lets you get a specific API client by passing the client’s token in the request.

GET /identity-management/v1/open-identities/tokens/{accessToken}{?actions}

Sample: /identity-management/v1/open-identities/tokens/akaa-onah2fsgph6i7sx2-j4vrsb3rbyqxuslo?actions=true

Parameter Type Sample Description
URL parameters
accessToken String akaa-onah2fsgph6i7sx2-j4vrsb3rbyqxuslo An access token identifies a collection of APIs belonging to an API client.
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Response Body:

{
    "identity": {
        "openIdentityId": "24n75iohuvt3ta2v",
        "clientName": "Client Name",
        "uiUserName": "johnDoe",
        "uiIdentityId": "1-abcd",
        "activeCredentialCount": 1,
        "createdDate": "2016-02-24T22:43:12Z",
        "createdBy": "jakeDoe",
        "clientDescription": "reporting client",
        "useLunaUserAccess": true,
        "allowAccountSwitch": true,
        "actions": {
            "delete": false,
            "transfer": false,
            "lock": true,
            "deactivateAll": true,
            "editAuth": true
        }
    },
    "groupAccess": [
        {
            "groupId": 18385,
            "roleId": 14,
            "isBlocked": false,
            "subGroups": [
                {
                    "groupId": 18436,
                    "roleId": null,
                    "isBlocked": false,
                    "subGroups": []
                }
            ]
        }
    ],
    "authorization": {
        "serviceProviderId": 1,
        "serviceProviderName": "LUNA",
        "authorizationId": 137850,
        "openIdentityId": "B-C-4NPCYX",
        "name": "IDM Auth",
        "description": "IDM Auth",
        "baseURL": "https://example.baseurl.akamaiapis.net/",
        "accessToken": "akaa-example-token",
        "services": [
            {
                "serviceId": 406,
                "serviceName": "Traffic Management Configurations",
                "description": "Traffic Management Configurations",
                "endPoint": "/config-gtm/v1/",
                "grantScopes": [
                    {
                        "name": "READ-ONLY",
                        "description": "READ-ONLY"
                    },
                    {
                        "name": "READ-WRITE",
                        "description": "READ-WRITE"
                    }
                ]
            }
        ],
        "ccuParams": {
            "purgeCpcodes": [
                461295,
                461145
            ],
            "purgeByCpcode": true,
            "purgeByCacheTag": true
        }
    }
}
  1. In Luna, Navigate to the OPEN Identity detail page.

  2. Retrieve the access token from the Authorizations section.

  3. Insert the access token in each endpoint where applicable.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

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
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, but once you change the status to DELETED, you have actually deleted it and it cannot be reactivated.

Identity

This object encapsulates the response schema for creating API client.

All object members are read-only, and always present.

Download schema: open-identity-by-access-token.json

Sample GET:

{
    "identity": {
        "openIdentityId": "24n75iohuvt3ta2v",
        "clientName": "Client Name",
        "uiUserName": "johnDoe",
        "uiIdentityId": "1-abcd",
        "activeCredentialCount": 1,
        "createdDate": "2016-02-24T22:43:12Z",
        "createdBy": "jakeDoe",
        "clientDescription": "reporting client",
        "useLunaUserAccess": true,
        "allowAccountSwitch": true,
        "actions": {
            "delete": false,
            "transfer": false,
            "lock": true,
            "deactivateAll": true,
            "editAuth": true
        }
    },
    "groupAccess": [
        {
            "groupId": 18385,
            "roleId": 14,
            "isBlocked": false,
            "subGroups": [
                {
                    "groupId": 18436,
                    "roleId": null,
                    "isBlocked": false,
                    "subGroups": []
                }
            ]
        }
    ],
    "authorization": {
        "serviceProviderId": 1,
        "serviceProviderName": "LUNA",
        "authorizationId": 137850,
        "openIdentityId": "B-C-4NPCYX",
        "name": "IDM Auth",
        "description": "IDM Auth",
        "baseURL": "https://example.baseurl.akamaiapis.net/",
        "accessToken": "akaa-example-token",
        "services": [
            {
                "serviceId": 406,
                "serviceName": "Traffic Management Configurations",
                "description": "Traffic Management Configurations",
                "endPoint": "/config-gtm/v1/",
                "grantScopes": [
                    {
                        "name": "READ-ONLY",
                        "description": "READ-ONLY"
                    },
                    {
                        "name": "READ-WRITE",
                        "description": "READ-WRITE"
                    }
                ]
            }
        ],
        "ccuParams": {
            "purgeCpcodes": [
                461295,
                461145
            ],
            "purgeByCpcode": true,
            "purgeByCacheTag": true
        }
    }
}

Identity members

Member Type Description
authorization Identity.authorization An API client’s combination of services and grant scopes that allow you to make calls with that client.
groupAccess Identity.groupAccess[] The groups an API client can access.
identity Identity.identity The API client. API clients contain a set of permissions and tokens, providing a user with access to specific APIs.
Identity.authorization: An API client’s combination of services and grant scopes that allow you to make calls with that 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.
authorizationId Integer Unique identifier of the authorization.
baseURL String The base URL for the service.
ccuParams Identity.authorization.ccuParams ccuParams are only applicable for CCU OPEN clients.
description String Description of the API client’s authorization.
name String Name of the authorization.
openIdentityId String The unique identifier of the API client.
serviceProviderId Integer A unique identifier for a service provider.
serviceProviderName String The name of the service provider, like Luna, DNS or CCU.
services Identity.authorization.services[] Lists APIs you’d like to use, like Diagnostic Tools or DevPops.
Identity.authorization.ccuParams: ccuParams are only applicable for CCU OPEN clients.
purgeByCacheTag Boolean If purgeByCacheTag is true you can purge by cache tag with your API client.
purgeByCpcode Boolean If purgeByCpCode is true you can purge that CP code with your API client.
purgeCpcodes Array Lists all CP codes that your API client is allowed to purge.
Identity.authorization.services[]: Lists APIs you’d like to use, like Diagnostic Tools or DevPops.
description String The description of a service.
endPoint String The endpoint to access a service.
grantScopes Identity.authorization.services[].grantScopes[] The amount of access you give to an API client on a per-service basis.
serviceId Integer A unique identifier for a service.
serviceName String The name of a service, like Diagnostic Tools, or Identity Management: API.
Identity.authorization.services[].grantScopes[]: The amount of access you give to an API client on a per-service basis.
description String The description of a grant scope.
name String The name of a grant scope.
Identity.groupAccess[]: 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 cannot access the child group.
parentGroupId String The unique identifier for the parent group within the group tree. If you are 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 Array Children of the parent group, represented as an array of Identity.groupAccess[] objects. Permissions cascade downward from parent to child unless the child group’s isBlocked is true.
Identity.identity: The API client. API clients contain a set of permissions and tokens, providing a user with access to specific APIs.
actions Identity.identity.actions[] Encapsulates the different ways you can edit an API client, including changing its owner, access rights to Luna services or resources, or deleting it.
activeCredentialCount Integer Number of credentials active for the API client.
allowAccountSwitch Boolean If you can use the API client to manage more than one account.
clientDescription String Description of the API client.
clientName String The API client’s human-readable name.
createdBy String The user who created the API client.
createdDate String Read-only. The date the API client was made.
openIdentityId String Unique identifier for an API client.
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.
useLunaUserAccess Boolean If the API client’s permissions are tied to a Luna user’s permissions.
Identity.identity.actions[]: Encapsulates the different ways you can edit an API client, including changing its owner, access rights to Luna services or resources, or deleting it.
deactivateAll Boolean If the client’s deactivateAll is true, you can deactivate all credentials for the API client at once. Otherwise, you need to deactivate the credentials individually.
delete Boolean If the client’s delete is true, you can delete the API client. If delete is false, contact an admin on your account to have them delete the client.
editAuth Boolean If the client’s editAuth is true, you can change the client’s group and role assignments, and which API services it can access.
lock Boolean If the client’s lock is true, you can lock the client to prevent anyone from using it to access services on Luna.
transfer Boolean If the client’s transfer is true, you can give this API client to a different user.

Errors

This section tells you about the Identity Management API’s error response format, and details the range of HTTP status codes the API produces.

Error responses

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

The following 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

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

Code Description
200 Request OK.
201 Resource created.
401 Unauthorized request.
402 Failed request.
403 Forbidden.
404 Resource not found.
405 Method not allowed.
415 Unsupported media type.
429 Too many requests.
500 Internal Server Error.
503 Service Unavailable.

Last modified: 9/14/2018