loading

Identity Management: User Administration API v2

Manage accounts for users, and control their access to groups and properties.

Learn more:

Overview

Identity Management: User Administration API lets administrators programmatically manage users and their access to Akamai applications and resources. Additionally, administrators can programmatically maintain user accounts and other general user information, manage groups and group access, and perform other administrative tasks.

To manage API clients, see the Identity Management API.

Who should use this API

Account administrators should use this API to perform tasks to or for other users in addition to all tasks regular users perform.

Only administrators can use this API to manage groups, create or update roles, edit their own information, or move properties between groups. If you’re not an administrator, you can use a part of this API to update your own profile information.

Get started

To configure this API for the first time:

  • 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: User Administration, and set the access level to ADMIN.

  • First-time users need to create an API client with access to this API through the Identity Management application in Akamai Control Center. Alternatively, administrators can create an API client on behalf of the user in the Identity Management application. Then, the user can generate credentials through the Identity Management application in Control Center.

API concepts

This section describes the conceptual objects you deal with when interacting with this API, and provides pointers to where you can learn more.

  • Group: Groups are organizational containers for the objects you use in Control Center. Groups can contain other groups, primary objects like properties, and secondary objects like edge hostnames or CP codes. Groups are organized as a nested tree structure that cascade permissions. You can move a nested group to another position within the tree structure, but that may affect users’ access to objects it contains due to cascading permissions.

  • Property: A configuration file specifying how Akamai serves your web content. The Property Manager API (PAPI) allows you to manage property configurations and assign them to groups when you first create them.

  • Blocked Property: Administrators can block a user’s access to any property, overriding any available role already assigned to a user to further restrict access.

  • Users: A user is a person with access to Control Center.

  • Profile: A profile refers to a user’s information such as address and personal phone number. Users can edit their own profiles, but only administrators can edit profiles belonging to other users. Users can’t disable their two-factor authentication (TFA) settings if the account they belong to has TFA enabled by default.

  • Administrators: Administrators are a subset of users with additional permissions. They can have different levels of access, like API provisioning, moving groups or properties, or creating new users or modify existing ones. Response data may be redacted based on your access rights if you’re a lower-level administrator.

  • Common Resources: This refers to commonly accessible read-only information that may apply across all users on an account. It includes locale, security policies, and the set of available products. The API provides a different set of common resource operations for access by administrators and for other users.

  • Notification: Users configure email notifications for reminders to rotate passwords, or to learn about maintenance issues for each product.

  • Role: Roles are lists of permissions that are explicitly tied to both a user and a group. Users need roles to act on objects in a group. It’s the combination of user, role, and group that grants a user access to the objects they need. Roles may restrict access for a limited set of a group’s resources.

  • Grantable Role: These contain certain Akamai-defined atomic permissions that, when grouped together, give you access to applications and resources. The permissions included in a grantable role depend on what products are available on your contract. Use the Contract API for information on the products associated with your contract.

Resources

This section provides details on the various operations of the API.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Groups  
List groups GET /identity-management/v2/user-admin/groups{?actions}
Get a group GET /identity-management/v2/user-admin/groups/{groupId}{?actions}
Create a new group POST /identity-management/v2/user-admin/groups/{groupId}
Modify a group’s name PUT /identity-management/v2/user-admin/groups/{groupId}
Delete a group DELETE /identity-management/v2/user-admin/groups/{groupId}
Move a group POST /identity-management/v2/user-admin/groups/move
List users affected by moving a group GET /identity-management/v2/user-admin/groups/move/{sourceGroupId}/{destinationGroupId}/affected-users{?userType}
Properties  
List properties GET /identity-management/v2/user-admin/properties{?groupId}
Get a property GET /identity-management/v2/user-admin/properties/{propertyId}{?groupId}
Move a property PUT /identity-management/v2/user-admin/properties/{propertyId}
List users for property GET /identity-management/v2/user-admin/properties/{propertyId}/users{?userType}
Block users PUT /identity-management/v2/user-admin/properties/{propertyId}/users/block
Get the resources of a property GET /identity-management/v2/user-admin/properties/{propertyId}/resources{?groupId}
Roles  
List roles GET /identity-management/v2/user-admin/roles{?actions,groupId,users,ignoreContext}
Create a role POST /identity-management/v2/user-admin/roles
Get a role GET /identity-management/v2/user-admin/roles/{roleId}{?actions,grantedRoles}
Edit a role PUT /identity-management/v2/user-admin/roles/{roleId}
Delete a role DELETE /identity-management/v2/user-admin/roles/{roleId}
List grantable roles GET /identity-management/v2/user-admin/roles/grantable-roles
Your User Profile  
View your profile GET /identity-management/v2/user-profile{?authGrants,notifications,actions}
Edit your profile PUT /identity-management/v2/user-profile/basic-info
Rotate your password POST /identity-management/v2/user-profile/change-password
Set two-factor authentication PUT /identity-management/v2/user-profile/tfa{?action}
Update notifications PUT /identity-management/v2/user-profile/notifications
Users, for Administrators  
List users GET /identity-management/v2/user-admin/ui-identities{?groupId,authGrants,actions}
Create a user POST /identity-management/v2/user-admin/ui-identities{?sendEmail}
Get a user GET /identity-management/v2/user-admin/ui-identities/{uiIdentityId}{?authGrants,notifications,actions}
Remove a user DELETE /identity-management/v2/user-admin/ui-identities/{uiIdentityId}
Update a user’s notifications PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/notifications
Reset a user’s password POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/reset-password{?sendEmail}
Update a user PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/basic-info
List blocked properties GET /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/groups/{groupId}/blocked-properties
Update blocked properties PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/groups/{groupId}/blocked-properties
Modify a user’s group and role assignments PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/auth-grants
Set a user’s two-factor authentication PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/tfa{?action}
Lock a user’s account POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/lock
Unlock a user’s account POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/unlock
Set a user’s password POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/set-password
Common Resources, for Administrators  
View password policy GET /identity-management/v2/user-admin/common/password-policy
View contact types GET /identity-management/v2/user-admin/common/contact-types
View supported countries GET /identity-management/v2/user-admin/common/countries
View states GET /identity-management/v2/user-admin/common/countries/{country}/states
View timeout policies GET /identity-management/v2/user-admin/common/timeout-policies
View languages GET /identity-management/v2/user-admin/common/supported-languages
View time zones GET /identity-management/v2/user-admin/common/timezones
View products GET /identity-management/v2/user-admin/common/notification-products
Common Resources, for Users  
View password policy for a user profile GET /identity-management/v2/user-profile/common/password-policy
View contact types for a user profile GET /identity-management/v2/user-profile/common/contact-types
View supported countries for a user profile GET /identity-management/v2/user-profile/common/countries
View states for a user profile GET /identity-management/v2/user-profile/common/countries/{country}/states
View timeout policies for a user profile GET /identity-management/v2/user-profile/common/timeout-policies
View languages for a user profile GET /identity-management/v2/user-profile/common/supported-languages
View time zones for a user profile GET /identity-management/v2/user-profile/common/timezones
View products for a user profile GET /identity-management/v2/user-profile/common/notification-products

List groups

List all groups in which you have a scope of admin for the current account and contract type. The account and contract type are determined by the access tokens in your API client.

GET /identity-management/v2/user-admin/groups{?actions}

Sample: /identity-management/v2/user-admin/groups?actions=true

Parameter Type Sample Description
Optional query parameters
actions Boolean true When enabled, the response includes information about actions such as edit or delete that you can take for the object. Not to be confused with the action parameter, which applies to the Set two-factor authentication operation.

Status 200 application/json

Object type: Group

Download schema: ListOfGroupResponse.json

Response body:

[
    {
        "groupId": 12345,
        "groupName": "Top Level group",
        "createdDate": "2012-04-28T00:00:00.000Z",
        "createdBy": "johndoe",
        "modifiedDate": "2012-04-28T00:00:00.000Z",
        "modifiedBy": "johndoe",
        "actions": {
            "edit": true,
            "delete": false
        },
        "subGroups": [
            {
                "groupId": 11111,
                "groupName": "First Level SubGroup",
                "createdDate": "2013-10-29T19:05:52.000Z",
                "createdBy": "johndoe",
                "modifiedDate": "2017-07-25T22:30:20.000Z",
                "modifiedBy": "lionelmessi",
                "parentGroupId": 12345,
                "actions": {
                    "edit": true,
                    "delete": false
                },
                "subGroups": [
                    {
                        "groupId": 54321,
                        "groupName": "Second Level SubGroup",
                        "createdDate": "2017-07-25T22:30:47.000Z",
                        "createdBy": "Company",
                        "modifiedDate": "2017-07-25T22:30:47.000Z",
                        "modifiedBy": "Company",
                        "parentGroupId": 11111,
                        "actions": {
                            "edit": true,
                            "delete": false
                        },
                        "subGroups": []
                    }
                ]
            }
        ]
    }
]

  1. If you want available actions returned for each group, enable the actions query parameter.

  2. Make a GET request to /identity-management/v2/user-admin/groups{?actions}.

The response contains an array of Group objects.

Get a group

Return a group’s details.

GET /identity-management/v2/user-admin/groups/{groupId}{?actions}

Sample: /identity-management/v2/user-admin/groups/19807?actions=true

Parameter Type Sample Description
URL path parameters
groupId Integer 19807 A unique identifier for a group.
Optional query parameters
actions Boolean true When enabled, the response includes information about actions such as edit or delete that you can take for the object. Not to be confused with the action parameter, which applies to the Set two-factor authentication operation.

Status 200 application/json

Object type: Group

Download schema: GroupResponse.json

Response body:

{
    "groupId": 12345,
    "groupName": "TopLevelGroup",
    "createdDate": "2012-04-28T00:00:00.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2012-04-28T00:00:00.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "edit": true,
        "delete": false
    },
    "subGroups": [
        {
            "groupId": 11111,
            "groupName": "First Level SubGroup",
            "createdDate": "2013-10-29T19:05:52.000Z",
            "createdBy": "johndoe",
            "modifiedDate": "2017-07-25T22:30:20.000Z",
            "modifiedBy": "lionelmessi",
            "parentGroupId": 12345,
            "actions": {
                "edit": true,
                "delete": false
            },
            "subGroups": [
                {
                    "groupId": 123456,
                    "groupName": "Second Level SubGroup",
                    "createdDate": "2017-07-25T22:30:47.000Z",
                    "createdBy": "Company",
                    "modifiedDate": "2017-07-25T22:30:47.000Z",
                    "modifiedBy": "Company",
                    "parentGroupId": 11111,
                    "actions": {
                        "edit": true,
                        "delete": false
                    },
                    "subGroups": []
                }
            ]
        }
    ]
}

  1. Run the List groups operation and select the relevant groupId.

  2. Optionally enable the actions query parameter to return the set of actions available to users for this group.

  3. Make a GET request to /identity-management/v2/user-admin/groups/{groupId}{?actions}.

The response is a Group object.

Create a new group

Create a new group within a parent group you specify in the request.

POST /identity-management/v2/user-admin/groups/{groupId}

Sample: /identity-management/v2/user-admin/groups/19807

Content-Type: application/json

Object type: Group

Download schema: GroupRequest.json

Request body:

{
    "groupName": "New Sub Group"
}
Parameter Type Sample Description
URL path parameters
groupId Integer 19807 A unique identifier for a group.

Status 200 application/json

Object type: Group

Download schema: GroupResponse.json

Response body:

{
    "groupId": 111898,
    "groupName": "New Sub Group",
    "parentGroupId": 19807,
    "createdDate": "2017-09-18T19:03:28.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-09-18T19:03:28.000Z",
    "modifiedBy": "johndoe"
}

  1. Create a Group object featuring only the groupName.

  2. POST the object to /identity-management/v2/user-admin/groups/{groupId}.

The response reflects the complete Group object.

Modify the name of a group

Change the name of the group.

PUT /identity-management/v2/user-admin/groups/{groupId}

Sample: /identity-management/v2/user-admin/groups/19807

Content-Type: application/json

Object type: Group

Download schema: GroupRequest.json

Request body:

{
    "groupName": "Change Group Name"
}
Parameter Type Sample Description
URL path parameters
groupId Integer 19807 A unique identifier for a group.

Status 201 application/json

Object type: Group

Download schema: GroupResponse.json

Response body:

{
    "groupId": 12345,
    "groupName": "Change Group Name",
    "createdDate": "2012-04-28T00:00:00.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2012-04-28T00:00:00.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "edit": true,
        "delete": false
    },
    "subGroups": [
        {
            "groupId": 11111,
            "groupName": "First Level SubGroup",
            "createdDate": "2013-10-29T19:05:52.000Z",
            "createdBy": "johndoe",
            "modifiedDate": "2017-07-25T22:30:20.000Z",
            "modifiedBy": "janelane",
            "parentGroupId": 12345,
            "actions": {
                "edit": true,
                "delete": false
            },
            "subGroups": [
                {
                    "groupId": 67890,
                    "groupName": "Second Level SubGroup",
                    "createdDate": "2017-07-25T22:30:47.000Z",
                    "createdBy": "Company",
                    "modifiedDate": "2017-07-25T22:30:47.000Z",
                    "modifiedBy": "Company",
                    "parentGroupId": 11111,
                    "actions": {
                        "edit": true,
                        "delete": false
                    },
                    "subGroups": []
                }
            ]
        }
    ]
}

  1. Run the List groups operation and select the relevant groupId.

  2. Run the Get a group operation.

  3. The response is a Group object. Edit the groupName in the object.

  4. PUT the object to /identity-management/v2/user-admin/groups/{groupId}.

The response reflects the modified Group object.

Delete a group

You can only delete a sub-group, and only if that sub-group doesn’t include any users.

DELETE /identity-management/v2/user-admin/groups/{groupId}

Sample: /identity-management/v2/user-admin/groups/19807

Parameter Type Sample Description
URL path parameters
groupId Integer 19807 A unique identifier for a group.

Status 204

  1. Run the List groups operation and select the relevant groupId URL parameter.

  2. Make a DELETE request to /identity-management/v2/user-admin/groups/{groupId}.

Move a group

Move a nested group into another group in the same account.

POST /identity-management/v2/user-admin/groups/move

Content-Type: application/json

Object type: MoveGroup

Download schema: MoveGroupRequest.json

Request body:

{
    "sourceGroupId": 12345,
    "destinationGroupId": 54321
}

Status 204

  1. Run the List groups operation.

  2. Select the groupId for the group you want to move, and assign it as the sourceGroupId.

  3. Select the groupId for the group you want to move it to, and assign it as the destinationGroupId.

  4. Create a MoveGroup object featuring the sourceGroupId and destinationGroupId.

  5. POST the object to /identity-management/v2/user-admin/groups/move.

List users affected by moving a group

List users who are affected when a group is moved. Users may lose or gain access to resources depending on the roles and permissions associated with the new parent group. Users with a userType of lostAccess lose their access to the source group. If the userType is gainAccess, they gain access to the resources in the source group. Users who have inherited access to a group lose access to that group if it moves out of its the hierarchy that gives them those access rights. If the group moves to another parent group to which they have access, they still have access to the group you move. Likewise, when a group is moved to its new location, users who inherit their access rights from the new parent group gain access to the resources in the group you move.

GET /identity-management/v2/user-admin/groups/move/{sourceGroupId}/{destinationGroupId}/affected-users{?userType}

Sample: /identity-management/v2/user-admin/groups/move/106532/19807/affected-users?userType=lostAccess

Parameter Type Sample Description
URL path parameters
sourceGroupId Integer 106532 The groupId for the group you want to move.
destinationGroupId Integer 19807 The groupId for the group you’re putting the other group into.
Optional query parameters
userType Enumeration lostAccess Filters users by whether they lost access or gained access. If set to lostAccess, the response includes users who lost access to the resources in the group that was moved. If set to gainAccess, the response includes users who gained access to the resources in the group that was moved.

Status 200 application/json

Object type: User

Download schema: ListOfMoveUserResponse.json

Response body:

[
    {
        "uiIdentityId": "A-B-12345",
        "firstName": "John",
        "lastName": "Doe",
        "accountId": "1-2ABCD",
        "email": "john.doe@mycompany.com",
        "uiUserName": "john.doe@mycompany.com",
        "lastLoginDate": "2017-08-03T21:15:27.000Z"
    },
    {
        "uiIdentityId": "1-2A3BCD",
        "firstName": "Lionel",
        "lastName": "Messi",
        "accountId": "1-2ABCD",
        "email": "lionel.messi@barcelona.com",
        "uiUserName": "lionel.messi@barcelona.com",
        "lastLoginDate": "2016-09-07T00:00:00.000Z"
    }
]

  1. Run the List groups operation.

  2. Select the groupId for the group you’re moving, and assign it as the sourceGroupId URL parameter.

  3. Select the groupId for the group you’re moving the group to, and assign it as the destinationGroupId URL parameter.

  4. Optionally set the userType query parameter to filter users who gain or lose access to the sourceGroup.

  5. Make a GET request to /identity-management/v2/user-admin/groups/move/{sourceGroupId}/{destinationGroupId}/affected-users{?userType}.

The response lists each User affected by moving the group.

List properties

Return a list of properties for an account. Include the groupId parameter in your request to filter the results by group.

GET /identity-management/v2/user-admin/properties{?groupId}

Sample: /identity-management/v2/user-admin/properties?groupId=3456789

Parameter Type Sample Description
Optional query parameters
groupId Integer 3456789 A unique identifier for a group.

Status 200 application/json

Object type: Property

Download schema: ListOfPropertyListItem.json

Response body:

[
    {
        "groupName": "Group 1",
        "groupId": 99999,
        "propertyId": 99999999,
        "propertyTypeDescription": "On Demand Media",
        "propertyName": "0rb-test-01.com",
        "actions": {
            "move": true
        }
    },
    {
        "groupName": "Group 2",
        "groupId": 99999,
        "propertyId": 88888888,
        "propertyTypeDescription": "On Demand Media",
        "propertyName": "0rb-test-01.com_clone",
        "actions": {
            "move": true
        }
    }
]

  1. Optionally run the List groups operation and select the groupId to filter results.

  2. Make a GET request to /identity-management/v2/user-admin/properties{?groupId}.

The response is a list of Property objects.

Get a property

Get information about a property.

GET /identity-management/v2/user-admin/properties/{propertyId}{?groupId}

Sample: /identity-management/v2/user-admin/properties/9678999?groupId=45678

Parameter Type Sample Description
URL path parameters
propertyId Integer 9678999 A unique identifier for a property.
Required query parameters
groupId Integer 45678 A unique identifier for a group.

Status 200 application/json

Object type: Property

Download schema: PropertyResponse.json

Response body:

{
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "doe.john@example.com",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "doe.john@example.com",
    "groupName": "Sales Team",
    "groupId": 45678,
    "arlConfigFile": "abc-dn123-abcde.akamaiorigin.net.xml",
    "propertyId": 9678999,
    "propertyName": "abc-dn123-abcde.akamaiorigin.net"
}

  1. Run the List properties operation and select the relevant propertyId and accompanying groupId.

  2. Make a GET request to /identity-management/v2/user-admin/properties/{propertyId}/{?groupId}.

The response is a Property object.

Move a property

Move a property from one group to another group. You can only move a property into another group within the same group hierarchy. Depending on your role in the destination group, you may lose access to resources the property uses.

PUT /identity-management/v2/user-admin/properties/{propertyId}

Sample: /identity-management/v2/user-admin/properties/9678999

Content-Type: application/json

Download schema: MovePropertyRequest.json

Request body:

{
    "sourceGroupId": 11111,
    "destinationGroupId": 22222
}
Parameter Type Sample Description
URL path parameters
propertyId Integer 9678999 A unique identifier for a property.

Status 204

  1. Run the List properties operation.

  2. Select the relevant propertyId of the property you want to move.

  3. From the same object, select the groupId and assign it as the sourceGroupId.

  4. Run the List groups operation and select the groupId for the group you want to move the property to as destinationGroupId.

  5. Create a MoveGroup object featuring the sourceGroupId and destinationGroupId.

  6. PUT the object to /identity-management/v2/user-admin/properties/{propertyId}.

List users for property

List users who can access this property.

GET /identity-management/v2/user-admin/properties/{propertyId}/users{?userType}

Sample: /identity-management/v2/user-admin/properties/9678999/users?userType=lostAccess

Parameter Type Sample Description
URL path parameters
propertyId Integer 9678999 A unique identifier for a property.
Optional query parameters
userType Enumeration lostAccess Indicates the type of users to get, either those who have lostAccess or the reverse gainAccess.

Status 200 application/json

Object type: User

Download schema: ListOfUserPropertyId.json

Response body:

[
    {
        "uiUserName": "aditparikh",
        "uiIdentityId": "B-3-146FAB9",
        "firstName": "Media",
        "lastName": "QA",
        "isBlocked": true
    },
    {
        "uiUserName": "amoody",
        "uiIdentityId": "B-C-IP9IND",
        "firstName": "Bert",
        "lastName": "Moody",
        "isBlocked": false
    }
]

  1. Run the List properties operation and select the relevant propertyId.

  2. From the same object, select the groupId.

  3. Make a GET request to /identity-management/v2/user-admin/properties/{propertyId}/users{?groupId}.

The response is an array of User objects.

Block users

Block the list of users on a property.

PUT /identity-management/v2/user-admin/properties/{propertyId}/users/block

Sample: /identity-management/v2/user-admin/properties/9678999/users/block

Content-Type: application/json

Download schema: ListOfUserBlockUIIdentities.json

Request body:

[
    {
        "uiIdentityId": "B-3-146FAB9"
    },
    {
        "uiIdentityId": "B-C-IP9IND"
    }
]
Parameter Type Sample Description
URL path parameters
propertyId Integer 9678999 A unique identifier for a property.

Status 200 application/json

Object type: User

Download schema: ListOfUserPropertyId.json

Response body:

[
    {
        "uiUserName": "aditparikh",
        "uiIdentityId": "B-3-146FAB9",
        "firstName": "Media",
        "lastName": "QA",
        "isBlocked": true
    },
    {
        "uiUserName": "amoody",
        "uiIdentityId": "B-C-IP9IND",
        "firstName": "Bert",
        "lastName": "Moody",
        "isBlocked": false
    }
]

Get property resources

List of resources the property uses.

GET /identity-management/v2/user-admin/properties/{propertyId}/resources{?groupId}

Sample: /identity-management/v2/user-admin/properties/9678999/resources?groupId=45678

Parameter Type Sample Description
URL path parameters
propertyId Integer 9678999 A unique identifier for a property.
Required query parameters
groupId Integer 45678 A unique identifier for a group.

Status 200 application/json

Object type: Resource

Download schema: ListOfResourceItem.json

Response body:

[
    {
        "resourceId": 111111,
        "resourceType": "arlfile",
        "resourceName": "abc-dn123-abcde.akamaiorigin.net.xml",
        "modifiedDate": "2017-09-07T17:00:58.000Z"
    },
    {
        "resourceId": 8988898,
        "resourceType": "cpcode",
        "resourceName": "mycpcodeexample(123456)",
        "modifiedDate": "2017-04-24T16:19:27.000Z"
    }
]

  1. Run the List properties operation and select the relevant propertyId.

  2. From the same object, select the groupId.

  3. Make a GET request to /identity-management/v2/user-admin/properties/{propertyId}/resources{?groupId}.

The response is an array of Resource objects.

List roles

List roles for the current account and contract type. The account and contract type are determined by the access tokens in your API client.

GET /identity-management/v2/user-admin/roles{?actions,groupId,users,ignoreContext}

Sample: /identity-management/v2/user-admin/roles?actions=true&groupId=1234567&users=true&ignoreContext=true

Parameter Type Sample Description
Optional query parameters
actions Boolean true When enabled, the response includes information about actions such as edit or delete that you can take for the object. Not to be confused with the action parameter, which applies to the Set two-factor authentication operation.
groupId Integer 1234567 A unique identifier for a group.
ignoreContext Boolean true When enabled, returns all the roles for the current account, ignoring the contract type associated with your API client.
users Boolean true When enabled, returns users assigned to the roles.

Status 200 application/json

Object type: Role

Download schema: ListOfRoleListItem.json

Response body:

[
    {
        "roleId": 123456,
        "roleName": "View Only",
        "roleDescription": "This role will allow you to view",
        "type": "custom",
        "createdDate": "2017-07-27T18:11:25.000Z",
        "createdBy": "john.doe@mycompany.com",
        "modifiedDate": "2017-07-27T18:11:25.000Z",
        "modifiedBy": "john.doe@mycompany.com",
        "actions": {
            "edit": true,
            "delete": true
        }
    },
    {
        "roleId": 13,
        "roleName": "Accounting",
        "roleDescription": "This role allows for 'read only'",
        "type": "standard",
        "createdBy": "Company",
        "modifiedBy": "Company",
        "actions": {
            "edit": false,
            "delete": false
        },
        "numUsers": 2,
        "users": [
            {
                "uiIdentityId": "A-B-1BCDEF",
                "firstName": "John",
                "lastName": "Doe",
                "accountId": "1-7XYZT",
                "email": "john.doe@mycompany.com",
                "lastLoginDate": "2017-08-03T21:15:27.000Z"
            },
            {
                "uiIdentityId": "1-ABCDE",
                "firstName": "Jane",
                "lastName": "Lane",
                "accountId": "1-7XYZA",
                "email": "lane.jane@mycompany.com",
                "lastLoginDate": "2016-09-07T00:00:00.000Z"
            }
        ]
    }
]

  1. Optionally enable the actions query parameter to return the actions available to users for this role.

  2. Optionally run the List groups operation and select the groupId you want to use to filter results.

  3. Optionally enable the users query parameter to return users who have roles assigned. This filters users at the account level.

  4. Optionally enable the ignoreContext query parameter to return roles regardless of context.

  5. Make a GET request to /identity-management/v2/user-admin/roles{?actions,groupId,users,ignoreContext}.

  6. The response is an array of Role objects.

Create a role

Create a custom role. Roles exist at the account level regardless of group, but are constrained by contract type. If you create a role under one contract type, you cannot apply that role to groups belonging to a different contract type, even if they’re in the same account.

POST /identity-management/v2/user-admin/roles

Content-Type: application/json

Object type: Role

Download schema: RoleRequestPost.json

Request body:

{
    "roleName": "Edit Reports",
    "roleDescription": "This role will let the users to Edit/Create Reports",
    "grantedRoles": [
        {
            "grantedRoleId": 2051
        }
    ]
}

Status 200 application/json

Object type: Role

Download schema: RoleWithGrantedRoles.json

Response body:

{
    "roleId": 12345678,
    "roleName": "Edit Role",
    "roleDescription": "This role will let the users to Edit/Create Reports",
    "type": "custom",
    "createdDate": "2017-09-11T13:43:54.005Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-09-11T13:43:54.005Z",
    "modifiedBy": "johndoe",
    "actions": {
        "edit": true,
        "delete": true
    },
    "grantedRoles": [
        {
            "grantedRoleId": 1234,
            "grantedRoleName": "RealUserMonitoring - View Only",
            "grantedRoleDescription": "View Real User Monitoring"
        }
    ],
    "users": [
        {
            "uiIdentityId": "A-B-12345",
            "firstName": "John",
            "lastName": "Doe",
            "accountId": "1-234A",
            "email": "john.doe@mycompany.com",
            "lastLoginDate": "2016-01-13T17:53:57Z"
        }
    ]
}

  1. Create a Role object.

  2. POST the object to /identity-management/v2/user-admin/roles.

The response reflects the complete Role object.

Get a role

Get details for a specific role.

GET /identity-management/v2/user-admin/roles/{roleId}{?actions,grantedRoles}

Sample: /identity-management/v2/user-admin/roles/45678?actions=true&grantedRoles=true

Parameter Type Sample Description
URL path parameters
roleId Integer 45678 A unique identifier for a role.
Optional query parameters
actions Boolean true When enabled, the response includes information about actions such as edit or delete that you can take for the object. Not to be confused with the action parameter, which applies to the Set two-factor authentication operation.
grantedRoles Boolean true When enabled, the response lists granted roles assigned for a role.

Status 200 application/json

Object type: Role

Download schema: RoleWithGrantedRoles.json

Response body:

{
    "roleId": 123456,
    "roleName": "Security View Only",
    "roleDescription": "This role will allow you to look at the security reports",
    "type": "custom",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "john.doe@mycompany.com",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "john.doe@mycompany.com",
    "actions": {
        "edit": false,
        "delete": false
    },
    "users": [
        {
            "uiIdentityId": "A-B-12345",
            "firstName": "John",
            "lastName": "Doe",
            "accountId": "1-2ABC",
            "email": "john.doe@mycompany.com",
            "lastLoginDate": "2017-08-03T21:15:27.000Z"
        },
        {
            "uiIdentityId": "1-2ABCD",
            "firstName": "Jane",
            "lastName": "Lane",
            "accountId": "1-7XYZ",
            "email": "lane.jane@mycompany.com",
            "lastLoginDate": "2016-09-07T00:00:00.000Z"
        }
    ],
    "grantedRoles": [
        {
            "grantedRoleId": 12345,
            "grantedRoleName": "SecurityViewOnly",
            "grantedRoleDescription": "Security View Only"
        }
    ]
}

  1. Run the List roles operation and select the relevant roleId.

  2. Optionally enable the grantedRoles query parameter to return roles granted to this role.

  3. Optionally enable the actions query parameter to return the set of actions available to users for this role.

  4. Optionally enable the users query parameter to return users who have roles assigned.

  5. Make a GET request to /identity-management/v2/user-admin/roles/{roleId}{?grantedRoles,actions,users}.

Edit a role

Add or remove permissions from a role. Additionally, edit the name, description, and so on.

PUT /identity-management/v2/user-admin/roles/{roleId}

Sample: /identity-management/v2/user-admin/roles/45678

Content-Type: application/json

Object type: Role

Download schema: RoleRequestPut.json

Request body:

{
    "roleName": "Edit Reports",
    "roleDescription": "This role will let the users to Edit/Create Reports",
    "grantedRoles": [
        {
            "grantedRoleId": 2063
        }
    ]
}
Parameter Type Sample Description
URL path parameters
roleId Integer 45678 A unique identifier for a role.

Status 200 application/json

Object type: Role

Download schema: RoleWithGrantedRoles.json

Response body:

{
    "roleId": 100645,
    "roleName": "Edit Reports",
    "roleDescription": "This role will let the users to Edit/Create Reports",
    "type": "custom",
    "createdDate": "2017-09-11T13:43:54.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-09-11T13:47:32.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "edit": true,
        "delete": true
    },
    "grantedRoles": [
        {
            "grantedRoleId": 2063,
            "grantedRoleName": "View Audience Analytics Reports",
            "grantedRoleDescription": "View Audience Analytics Reports"
        }
    ]
}

  1. Run the List roles operation and select the relevant roleId.

  2. Run the Get a role operation.

  3. Modify the response object.

  4. PUT the object back to /identity-management/v2/user-admin/roles/{roleId}.

The response reflects the modified Role object.

Delete a role

This operation is only allowed if the role isn’t assigned to any users.

DELETE /identity-management/v2/user-admin/roles/{roleId}

Sample: /identity-management/v2/user-admin/roles/45678

Parameter Type Sample Description
URL path parameters
roleId Integer 45678 A unique identifier for a role.

Status 204

  1. Run the List roles operation and select the relevant roleId.

  2. Make a DELETE request to /identity-management/v2/user-admin/roles/{roleId}.

List grantable roles

List which grantable roles you can include in a new custom role or add to an existing custom role.

GET /identity-management/v2/user-admin/roles/grantable-roles

Status 200 application/json

Object type: GrantableRole

Download schema: ListOfGrantedRole.json

Response body:

[
    {
        "grantedRoleId": 2051,
        "grantedRoleName": "WAF Strict WhiteList",
        "grantedRoleDescription": "WAF Strict WhiteList"
    },
    {
        "grantedRoleId": 1032,
        "grantedRoleName": "License Delivery Configurations - Manage",
        "grantedRoleDescription": "Manage License Delivery Configurations"
    },
    {
        "grantedRoleId": 2063,
        "grantedRoleName": "View Audience Analytics Reports",
        "grantedRoleDescription": "View Audience Analytics Reports"
    },
    {
        "grantedRoleId": 77852,
        "grantedRoleName": "RealUserMonitoring - View Only",
        "grantedRoleDescription": "View Real User Monitoring"
    },
    {
        "grantedRoleId": 32,
        "grantedRoleName": "Enhanced DNS - All privileges (add/edit/view)",
        "grantedRoleDescription": "Add/Edit/View Enhanced DNS - All privileges"
    }
]

View your profile

Return your own profile information. To make changes to your profile, run the Edit your profile operation.

GET /identity-management/v2/user-profile{?authGrants,notifications,actions}

Sample: /identity-management/v2/user-profile?authGrants=true&notifications=true&actions=true

Parameter Type Sample Description
Optional query parameters
actions Boolean true When enabled, the response includes information about actions such as edit or delete that you can take for the object. Not to be confused with the action parameter, which applies to the Set two-factor authentication operation.
authGrants Boolean true When enabled, include the list of your group and role assignments.
notifications Boolean true When enabled, include which product notifications you subscribe to.

Status 200 application/json

Object type: User

Download schema: UserResponse.json

Response body:

{
    "uiIdentityId": "A-B-123456",
    "firstName": "John",
    "lastName": "Doe",
    "uiUserName": "john.doe@mycompany.com",
    "email": "john.doe@mycompany.com",
    "lastLoginDate": "2016-01-13T17:53:57Z",
    "tfaEnabled": true,
    "country": "USA",
    "phone": "3456788765",
    "contactType": "Prolexic",
    "isLocked": false,
    "timeZone": "GMT",
    "preferredLanguage": "English",
    "sessionTimeOut": 30,
    "passwordExpiryDate": "2018-01-13T17:53:57Z",
    "secondaryEmail": "john-doe@gmail.com",
    "mobilePhone": "3456787657",
    "address": "first Street",
    "city": "Santa Clara",
    "state": "CA",
    "zipCode": "34567",
    "jobTitle": "Engineer",
    "actions": {
        "resetPassword": true,
        "delete": true,
        "edit": true,
        "apiClient": true,
        "thirdPartyAccess": true
    },
    "authGrants": [
        {
            "groupId": 12345,
            "groupName": "MyGroup",
            "roleId": 16,
            "roleName": "Publisher",
            "roleDescription": "This is a new role that has been created to"
        }
    ],
    "notifications": {
        "enable": true,
        "options": {
            "upgrade": [
                "NetStorage",
                "Other Upgrade Notifications (Planned)"
            ],
            "proactive": [
                "EdgeScape",
                "EdgeSuite (HTTP Content Delivery)"
            ],
            "passwordExpiry": true,
            "newUserNotification": true
        }
    }
}

  1. Enable the actions query parameter to return the set of actions available to users for this user.

  2. Enable the authGrants query parameter to return a list of the user’s group and role assignments.

  3. Enable the notifications query parameter to return a list of product-notification emails a user subscribes to.

  4. Make a GET request to /identity-management/v2/user-admin/user-profile{?actions,authGrants,notifications}.

The response is a User object.

Edit your profile

Update your basic profile information. You can update simple items like your name or phone number, but you cannot update your group or role assignments through this operation.

PUT /identity-management/v2/user-profile/basic-info

Content-Type: application/json

Object type: User

Download schema: UpdateUserBasicInfoRequest.json

Request body:

{
    "firstName": "John",
    "lastName": "Doe",
    "tfaEnabled": true,
    "country": "USA",
    "phone": "3456788765",
    "contactType": "Billing",
    "timeZone": "GMT",
    "preferredLanguage": "English",
    "sessionTimeOut": 30,
    "secondaryEmail": "john.doe@mycompany.com",
    "mobilePhone": "3456787657",
    "address": "first Street",
    "city": "Santa Clara",
    "state": "CA",
    "zipCode": "34567",
    "jobTitle": "Engineer"
}

Status 200 application/json

Object type: User

Download schema: UserResponse.json

Response body:

{
    "uiIdentityId": "1-ABCDE",
    "firstName": "John",
    "lastName": "Doe",
    "tfaEnabled": true,
    "country": "USA",
    "email": "john.doe@mycompany.com",
    "phone": "3456788765",
    "contactType": "Billing",
    "timeZone": "GMT",
    "preferredLanguage": "English",
    "sessionTimeOut": 30,
    "secondaryEmail": "john-doe@gmail.com",
    "mobilePhone": "3456787657",
    "address": "first Street",
    "city": "Santa Clara",
    "state": "CA",
    "zipCode": "34567",
    "jobTitle": "Engineer"
}

  1. Run the View your profile operation to get your user profile.

  2. Edit the User response object.

  3. PUT the object to /identity-management/v2/user-admin/user-profile/basic-info.

The response reflects the modified User object.

Rotate your password

To update or change your password, include your old password and your new password in the request body. Run the View password policy operation before you create your new password to ensure it adheres to your policy. If you pass your existing password incorrectly and make too many login attempts, your account locks.

POST /identity-management/v2/user-profile/change-password

Content-Type: application/json

Object type: RotatePassword

Download schema: ChangePasswordRequest.json

Request body:

{
    "currentPassword": "abcbd",
    "newPassword": "abcdg"
}

Status 204

  1. Create a RotatePassword object, featuring both currentPassword and newPassword.

  2. POST the object to /identity-management/v2/user-admin/user-profile/change-password.

Set two-factor authentication

Enable or disable TFA on your profile. An account administrator must disable TFA for you if the account is set to enable. If the account doesn’t specify a TFA setting, you can disable TFA on your profile yourself. You can always set TFA to enable regardless of account-level settings. If you have TFA enabled, reset TFA clears your TFA settings and you’ll be asked to set up TFA the next time you log in to Control Center.

PUT /identity-management/v2/user-profile/tfa{?action}

Sample: /identity-management/v2/user-profile/tfa?action=enable

Parameter Type Sample Description
Required query parameters
action Enumeration enable The actions you can perform for TFA on your own profile, either enable, disable, or reset. Not to be confused with the actions parameter, which applies to the various operations that get user data.

Status 204

  1. Optionally specify the action query parameter to enable, disable, or reset TFA settings.

  2. Make a PUT request to /identity-management/v2/user-admin/user-profile/tfa{?action}.

Update notifications

Subscribe to notifications emails for password expiration reminders, proactive maintenance emails, and upgrade notification emails. Make a PUT request with a Notifications object.

PUT /identity-management/v2/user-profile/notifications

Content-Type: application/json

Object type: Notifications

Download schema: NotificationsRequest.json

Request body:

{
    "enableEmailNotifications": true,
    "options": {
        "upgrade": [
            "NetStorage",
            "Other Upgrade Notifications (Planned)"
        ],
        "proactive": [
            "EdgeScape",
            "EdgeSuite (HTTP Content Delivery)"
        ],
        "passwordExpiry": true,
        "newUserNotification": true
    }
}

Status 200 application/json

Object type: Notifications

Download schema: NotificationsResponse.json

Response body:

{
    "enableEmailNotifications": true,
    "options": {
        "upgrade": [
            "NetStorage",
            "Other Upgrade Notifications (Planned)"
        ],
        "proactive": [
            "EdgeScape",
            "EdgeSuite (HTTP Content Delivery)"
        ],
        "passwordExpiry": true,
        "newUserNotification": true
    }
}

List users

Return a list of users who have access on this account. The account is determined by the tokens in your API client. You can pass a groupId to filter users based on group. Additionally, you can return additional user information such as what product notifications they subscribe to, or what group and role assignments they have. Set the actions parameter to true to return the actions you can take on each user.

GET /identity-management/v2/user-admin/ui-identities{?groupId,authGrants,actions}

Sample: /identity-management/v2/user-admin/ui-identities?groupId=19807&authGrants=true&actions=true

Parameter Type Sample Description
Optional query parameters
actions Boolean true When enabled, the response includes information about actions such as edit or delete that you can take for the object. In this case, users. Not to be confused with the action parameter, which applies to the Set two-factor authentication operation.
authGrants Boolean true When enabled, include the list of the user’s group and role assignments.
groupId Integer 19807 A unique identifier for a group.

Status 200 application/json

Object type: User

Download schema: ListOfUserResponse.json

Response body:

[
    {
        "uiIdentityId": "A-B-123456",
        "firstName": "John",
        "lastName": "Doe",
        "uiUserName": "johndoe",
        "email": "john.doe@mycompany.com",
        "accountId": "1-123A",
        "lastLoginDate": "2016-01-13T17:53:57Z",
        "tfaEnabled": true,
        "tfaConfigured": true,
        "isLocked": false,
        "actions": {
            "resetPassword": true,
            "delete": true,
            "edit": true,
            "apiClient": true,
            "thirdPartyAccess": true,
            "isCloneable": true,
            "editProfile": true,
            "canEditTFA": false
        },
        "authGrants": [
            {
                "groupId": 12345,
                "roleId": 12,
                "groupName": "mygroup",
                "roleName": "admin",
                "roleDescription": "This is a new role that has been created to",
                "isBlocked": false
            }
        ]
    }
]

  1. Run the List groups operation and select the relevant groupId.

  2. Enable the authGrants query parameter to return users’ groups and role assignments.

  3. Enable the actions query parameter to return what actions you can take on each user.

  4. Make a GET request to /identity-management/v2/user-admin/ui-identities{?groupId,authGrants,notifications,actions}.

The response is an array of User objects.

Create a user

Create a new user in the account specified in your own API client credentials or clone an existing user’s role assignments. Optionally, send a randomly generated one-time use password to the new user. If you send the email with the password directly to the user, the response for this operation doesn’t include that password. If you don’t send the password to the user through email, the password is included in the response.

POST /identity-management/v2/user-admin/ui-identities{?sendEmail}

Sample: /identity-management/v2/user-admin/ui-identities?sendEmail=false

Content-Type: application/json

Object type: User

Download schema: CreateUserRequest.json

Request body:

{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@mycompany.com",
    "phone": "(123) 321-1234",
    "timeZone": "GMT",
    "tfaEnabled": true,
    "contactType": "Billing",
    "preferredLanguage": "English",
    "sessionTimeOut": 64800,
    "address": "TBD",
    "city": "TBD",
    "state": "CA",
    "country": "USA",
    "secondaryEmail": "john-doe@gmail.com",
    "mobilePhone": "3456787657",
    "zipCode": "34567",
    "jobTitle": "Engineer",
    "authGrants": [
        {
            "groupId": 12345,
            "roleId": 3,
            "groupName": "MyGroup",
            "roleName": "Admin",
            "roleDescription": "This role provides the maximum access to users.",
            "subGroups": [
                {
                    "groupId": 54321,
                    "groupName": "MySubGroup",
                    "subGroups": [
                        {
                            "groupId": 56789,
                            "groupName": "MyNewSubGroup"
                        }
                    ]
                }
            ]
        }
    ],
    "notifications": {
        "enableEmailNotifications": true,
        "options": {
            "upgrade": [
                "NetStorage",
                "Other Upgrade Notifications (Planned)"
            ],
            "proactive": [
                "EdgeScape",
                "EdgeSuite (HTTP Content Delivery)"
            ],
            "passwordExpiry": true,
            "newUserNotification": true
        }
    }
}
Parameter Type Sample Description
Optional query parameters
sendEmail Boolean false When sendEmail=true, send a one-time password to the new user.

Status 200 application/json

Object type: User

Download schema: UserResponse.json

Response body:

{
    "uiIdentityId": "A-BC-1234567",
    "userPassword": "bcasXY8",
    "firstName": "John",
    "lastName": "Doe",
    "uiUserName": "john.doe@mycompany.com",
    "email": "john.doe@mycompany.com",
    "phone": "(123) 321-1234",
    "timeZone": "GMT",
    "tfaEnabled": true,
    "contactType": "Billing",
    "preferredLanguage": "English",
    "sessionTimeOut": 64800,
    "passwordExpiryDate": "2018-05-05T22:38:39.000Z",
    "address": "TBD",
    "city": "TBD",
    "state": "CA",
    "country": "USA",
    "authGrants": [
        {
            "groupId": 12345,
            "roleId": 3,
            "groupName": "MyGroup",
            "roleName": "Admin",
            "roleDescription": "This role provides the maximum access to users.",
            "subGroups": [
                {
                    "groupId": 54321,
                    "groupName": "MySubGroup",
                    "subGroups": [
                        {
                            "groupId": 56789,
                            "groupName": "MyNewSubGroup"
                        }
                    ]
                }
            ]
        }
    ],
    "actions": {
        "resetPassword": true,
        "edit": true,
        "isCloneable": true,
        "delete": true,
        "thirdPartyAccess": false,
        "apiClient": true
    },
    "notifications": {
        "enableEmailNotifications": true,
        "options": {
            "upgrade": [
                "24x7"
            ],
            "proactive": [
                "Security"
            ],
            "passwordExpiry": true,
            "newUserNotification": true
        }
    }
}

  1. Enable the sendEmail query parameter to send the new user a randomly generated, one-time use password.

  2. Create a User object. Optionally, use the cloneFrom member to clone an existing user’s role assignments. In this case, don’t include the authGrantsmember too.

  3. POST the object to /identity-management/v2/user-admin/ui-identities{?sendEmail}.

The response reflects the complete User object.

Get a user

Return a specific user’s profile.

GET /identity-management/v2/user-admin/ui-identities/{uiIdentityId}{?authGrants,notifications,actions}

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE?authGrants=true&notifications=true&actions=true

Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.
Optional query parameters
actions Boolean true When enabled, the response includes information about actions such as edit or delete that you can take for the object. In this case, users. Not to be confused with the action parameter, which applies to the Set two-factor authentication operation.
authGrants Boolean true When enabled, include the list of your group and role assignments.
notifications Boolean true When enabled, include which product notifications you subscribe to.

Status 200 application/json

Object type: User

Download schema: UserResponse.json

Response body:

[
    {
        "uiIdentityId": "A-B-123456",
        "firstName": "John",
        "lastName": "Doe",
        "uiUserName": "johndoe",
        "email": "john.doe@mycompany.com",
        "accountId": "1-123A",
        "phone": "3456788765",
        "timezone": "GMT",
        "lastLoginDate": "2016-01-13T17:53:57Z",
        "contactType": "Billing",
        "preferredLanguage": "English",
        "sessionTimeOut": 14400,
        "passwordExpiryDate": "2018-01-13T17:53:57Z",
        "secondaryEmail": "john_doe@gmail.com",
        "mobilePhone": "3456789999",
        "street": "First Street",
        "city": "Santa Clara",
        "state": "CA",
        "zipCode": "34567",
        "country": "USA",
        "jobTitle": "engineer",
        "isLocked": false,
        "notifications": {
            "enableEmailNotifications": true,
            "options": {
                "upgrade": [
                    "NetStorage",
                    "Other Upgrade Notifications (Planned)"
                ]
            },
            "proactive": [
                "EdgeScape",
                "EdgeSuite (HTTP Content Delivery)"
            ],
            "passwordExpiry": true,
            "newUserNotification": true
        },
        "tfaEnabled": true,
        "actions": {
            "resetPassword": true,
            "delete": true,
            "edit": true,
            "apiClient": true,
            "thirdPartyAccess": true,
            "isCloneable": true
        },
        "authGrants": [
            {
                "groupId": 12345,
                "roleId": 12,
                "groupName": "mygroup",
                "roleName": "admin",
                "roleDescription": "This is a new role that has been created to",
                "isBlocked": false
            }
        ]
    }
]

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Enable the authGrants query parameter to return users’ groups and role assignments.

  3. Enable the notifications query parameter to return which product-notification emails a user subscribes to.

  4. Enable the actions query parameter to return what actions you can take on each user.

  5. Make a GET request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}{?actions,authGrants,notifications}.

The response is a User object.

Remove a user

You can only delete users who don’t have any API or Webservices clients. To delete users, first transfer their API clients and delete their Webservices clients.

DELETE /identity-management/v2/user-admin/ui-identities/{uiIdentityId}

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE

Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.

Status 200

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Make a DELETE request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}.

Update user notifications

Subscribe or un-subscribe users to product notification emails.

PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/notifications

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/notifications

Content-Type: application/json

Object type: Notifications

Download schema: NotificationsRequest.json

Request body:

{
    "enableEmailNotifications": true,
    "options": {
        "upgrade": [
            "NetStorage",
            "Other Upgrade Notifications (Planned)"
        ],
        "proactive": [
            "EdgeScape",
            "EdgeSuite (HTTP Content Delivery)"
        ],
        "passwordExpiry": true,
        "newUserNotification": true
    }
}
Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.

Status 200 application/json

Object type: Notifications

Download schema: NotificationsResponse.json

Response body:

{
    "enableEmailNotifications": true,
    "options": {
        "upgrade": [
            "NetStorage",
            "Other Upgrade Notifications (Planned)"
        ],
        "proactive": [
            "EdgeScape",
            "EdgeSuite (HTTP Content Delivery)"
        ],
        "passwordExpiry": true,
        "newUserNotification": true
    }
}

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Build a Notifications object.

  3. PUT the object to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/notifications.

The response reflects the Notifications object.

Reset user password

Optionally send a one-time use password to the user. If you send the email with the password directly to the user, the response for this operation doesn’t include that password. If you don’t send the password to the user through email, the password is included in the response.

POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/reset-password{?sendEmail}

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/reset-password?sendEmail=false

Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.
Optional query parameters
sendEmail Boolean false When sendEmail=true, send a one-time password to the new user.

Status 200 application/json

Object type: RotatePassword

Download schema: PasswordResponse.json

Response body:

{
    "newPassword": "abc123"
}

Status 204

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Enable the sendEmail query parameter to send the new user a randomly generated, one-time use password.

  3. Make a POST request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/reset-password{?sendEmail}.

If sendEmail is false, a 200 response object contains the user’s new password, otherwise it’s a simple 204 response.

Update a user

Modify user information. Pass the entire body of data in the request, including members you’re not changing, or unspecified data will be removed.

PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/basic-info

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/basic-info

Content-Type: application/json

Object type: User

Download schema: UpdateUserBasicInfoRequest.json

Request body:

{
    "firstName": "John",
    "lastName": "Doe",
    "tfaEnabled": true,
    "country": "USA",
    "phone": "3456788765",
    "contactType": "Billing",
    "timeZone": "GMT",
    "preferredLanguage": "English",
    "sessionTimeOut": 30,
    "secondaryEmail": "john.doe@mycompany.com",
    "mobilePhone": "3456787657",
    "address": "first Street",
    "city": "Santa Clara",
    "state": "CA",
    "zipCode": "34567",
    "jobTitle": "Engineer"
}
Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.

Status 200 application/json

Object type: User

Download schema: UserResponse.json

Response body:

{
    "uiIdentityId": "1-ABCDE",
    "firstName": "John",
    "lastName": "Doe",
    "tfaEnabled": true,
    "country": "USA",
    "email": "john.doe@mycompany.com",
    "phone": "3456788765",
    "contactType": "Billing",
    "timeZone": "GMT",
    "preferredLanguage": "English",
    "sessionTimeOut": 30,
    "secondaryEmail": "john-doe@gmail.com",
    "mobilePhone": "3456787657",
    "address": "first Street",
    "city": "Santa Clara",
    "state": "CA",
    "zipCode": "34567",
    "jobTitle": "Engineer"
}

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Run the Get a user operation.

  3. Modify the response object.

  4. PUT the object to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/basic-info.

The response reflects the modified User object.

List blocked properties

Return all properties a user doesn’t have access to in a group

GET /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/groups/{groupId}/blocked-properties

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/groups/19807/blocked-properties

Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.
groupId Integer 19807 A unique identifier for a group.

Status 200 application/json

Download schema: ListOfInteger.json

Response body:

[
    11111111,
    22222222
]

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Run the List groups operation and select the relevant groupId.

  3. Make a GET request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/groups/{groupId}/blocked-properties.

  4. The response is a list of propertyId values.

  5. Optionally run the Get a property operation to get more information on a specific property.

Update blocked properties

Remove or grant user access to properties. By default, users have access to all properties in a group.

PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/groups/{groupId}/blocked-properties

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/groups/19807/blocked-properties

Content-Type: application/json

Download schema: ListOfInteger.json

Request body:

[
    11111111,
    22222222
]
Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.
groupId Integer 19807 A unique identifier for a group.

Status 200 application/json

Download schema: ListOfInteger.json

Response body:

[
    11111111,
    22222222
]

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Run the List groups operation and select the relevant groupId.

  3. Run the List properties operation to get a set of propertyId values.

  4. Create an array of propertyId values to pass in the request body.

  5. PUT the array to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/groups/{groupId}/blocked-properties.

The response is a list of propertyId values.

Modify user group and role assignments

Edit what groups a user has access to, and how the use can interact with the objects in those groups.

PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/auth-grants

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/auth-grants

Content-Type: application/json

Download schema: ListOfAuthGrantRequest.json

Request body:

[
    {
        "groupId": 12345,
        "roleId": 16,
        "subGroups": [
            {
                "groupId": 54321,
                "roleId": null,
                "subGroups": []
            }
        ]
    }
]
Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.

Status 200 application/json

Download schema: ListOfAuthGrantResponse.json

Response body:

[
    {
        "groupId": 12345,
        "roleId": 16,
        "groupName": "Company",
        "roleName": "Publisher",
        "roleDescription": "This is a new role that has been created to",
        "isBlocked": false,
        "subGroups": [
            {
                "groupId": 11111,
                "roleId": null,
                "groupName": "Sub Group",
                "roleName": "",
                "roleDescription": "",
                "isBlocked": false,
                "subGroups": []
            }
        ]
    }
]

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Form a User.authGrants[] object.

  3. Make a PUT request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/authGrants.

  4. The response is a User.authGrants[] object.

Set user two-factor authentication

Actions for this operation are enable, disable, and reset. Users can make five attempts to log in with TFA before their accounts lock. If the account gets locked, use reset value to unlock.

PUT /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/tfa{?action}

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/tfa?action=enable

Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.
Required query parameters
action String enable Can be either of enable, disable or reset.

Status 204

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Set the action query parameter to enable, disable, or reset.

  3. Make a PUT request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/tfa{?action}.

Lock user account

Prevent a user from logging in to Control center.

POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/lock

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/lock

Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.

Status 204

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Make a POST request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/lock.

Unlock user account

Release the lock on a user’s account and allow them to access Control Center.

POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/unlock

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/unlock

Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.

Status 204

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Make a POST request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/unlock.

Set user password

Set a specific password for a user. This differs from Reset a user’s password because this password may be used more than once, and isn’t randomly generated.

POST /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/set-password

Sample: /identity-management/v2/user-admin/ui-identities/1-ABCDE/set-password

Content-Type: application/json

Object type: RotatePassword

Download schema: SetPasswordRequest.json

Request body:

{
    "newPassword": "abc123"
}
Parameter Type Sample Description
URL path parameters
uiIdentityId String 1-ABCDE A unique identifier for a user.

Status 204

  1. Run the List users operation and select the relevant uiIdentityId URL parameter.

  2. Enable the sendEmail query parameter to send the new user a randomly generated, one-time use password.

  3. Make a POST request to /identity-management/v2/user-admin/ui-identities/{uiIdentityId}/set-password{?sendEmail}.

If sendEmail is false, a 200 response object contains the user’s new password, otherwise it’s a simple 204 response.

View password policy

Return the password policy for the current account. The current account is determined by the tokens in your API client. Administrators use this operation to set a user’s password policy. Users who modify it need to run View password policy for a user profile.

GET /identity-management/v2/user-admin/common/password-policy

Status 200 application/json

Object type: PasswordPolicy

Download schema: PortalPasswordClass.json

Response body:

{
    "pwclass": "aka90",
    "minLength": 8,
    "minLetters": 1,
    "minDigits": 1,
    "caseDif": 0,
    "minNonAlpha": 0,
    "maxRepeating": 2,
    "minReuse": 4,
    "rotateFrequency": 90
}

View contact types

List all the possible contact types that Akamai supports. Use the values from this operation to add or update a user’s contactType. Administrators use this operation to set a user’s contact type. Users who modify it need to run View contact types for a user profile.

GET /identity-management/v2/user-admin/common/contact-types

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "Billing",
    "Technical Decision Maker",
    "Business Decision Maker",
    "Security"
]

View supported countries

Return all the possible countries that Akamai supports. Use the values from this operation to add or update a user’s country information. Administrators use this operation to set a user’s country. Users who modify it need to run View supported countries for a user profile.

GET /identity-management/v2/user-admin/common/countries

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "Lao People's Democratic Republ",
    "Greece",
    "Greenland",
    "Grenada",
    "Tanzania, United Republic of",
    "Thailand",
    "Togo",
    "Tokelau",
    "Tonga",
    "Djibouti",
    "Dominica",
    "Christmas Island",
    "Cocos (Keeling) Islands",
    "Colombia",
    "Comoros",
    "Curacao"
]

View states

List U.S. states or Canadian provinces. If country=USA you may enter a value of TBD if you don’t know a user’s state. Administrators use this operation to set a user’s state. Users who modify it need to run View states for a user profile.

GET /identity-management/v2/user-admin/common/countries/{country}/states

Sample: /identity-management/v2/user-admin/common/countries/canada/states

Parameter Type Sample Description
URL path parameters
country String canada Specifies a U.S. state or Canadian province.

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "AB",
    "BC",
    "PQ",
    "NS",
    "NT",
    "NU",
    "QC",
    "YK",
    "NB",
    "MB",
    "PE",
    "TBD",
    "NF",
    "SK",
    "ON"
]

  1. Run the View supported countries operation.

  2. Choose a value from the response array and assign it as the country URL parameter.

  3. Make a GET request to /identity-management/v2/user-admin/common/countries/{country}/states.

The response is a list of states or provinces.

View timeout policies

Lists all the possible session timeout policies that Akamai supports. Use the values from this operation to set the sessionTimeout for a user. The name for each timeout period is in minutes, and the time value is in seconds. Administrators use this operation to set a user’s timeout policy. Users who modify it need to run View timeout policies for a user profile.

GET /identity-management/v2/user-admin/common/timeout-policies

Status 200 application/json

Object type: TimeoutPolicy

Download schema: ListOfSessionTimeoutPolicy.json

Response body:

[
    {
        "name": "after15Minutes",
        "value": 900
    },
    {
        "name": "after30Minutes",
        "value": 1800
    },
    {
        "name": "after45Minutes",
        "value": 2700
    },
    {
        "name": "after1Hour",
        "value": 3600
    },
    {
        "name": "after2Hours",
        "value": 7200
    },
    {
        "name": "after4Hours",
        "value": 14400
    },
    {
        "name": "after18Hours",
        "value": 64800
    }
]

View languages

List all the possible languages Akamai supports. Use the values from this API to set the preferred language for a user. Users should see Control Center in the language you set for them. Administrators use this operation to set a user’s preferred language. Users who modify it need to run View languages for a user profile.

GET /identity-management/v2/user-admin/common/supported-languages

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "Deutsch",
    "English",
    "Espa\u00f1ol",
    "Espa\u00f1ol (Espa\u00f1a)",
    "Fran\u00e7ais",
    "Italiano",
    "Portugu\u00eas",
    "\u4e2d\u6587 (\u7b80\u4f53)",
    "\u4e2d\u6587 (\u7e41\u9ad4)",
    "\u65e5\u672c\u8a9e",
    "\ud55c\uad6d\uc5b4"
]

View time zones

List all time zones Akamai supports. Time zones are in ISO 8601 format. Use the values from this operation to set the timeZone for a user. Administrators use this operation to set a user’s time zone. Users who modify it need to run View time zones for a user profile.

GET /identity-management/v2/user-admin/common/timezones

Status 200 application/json

Object type: TimeZone

Download schema: ListOfTimeZones.json

Response body:

[
    {
        "timezone": "Asia/Rangoon",
        "description": "Asia/Rangoon GMT+6",
        "offset": "+6",
        "posix": "Asia/Rangoon"
    },
    {
        "timezone": "Australia/Sydney",
        "description": "Australia/Sydney GMT+10",
        "offset": "+10",
        "posix": "Australia/Sydney"
    },
    {
        "timezone": "Etc/GMT+3",
        "description": "Etc/GMT+3",
        "offset": "+3",
        "posix": "Etc/GMT-3"
    }
]

View products

Return all products a user can subscribe to and receive notifications for on the account. The account is determined by the tokens in your API client. Administrators use this operation to set the products for which users receive notifications. Users who modify this set need to run View products for a user profile.

GET /identity-management/v2/user-admin/common/notification-products

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "EdgeComputing for Java",
    "Streaming",
    "Enhanced DNS",
    "Site Delivery",
    "Secure FreeFlow (HTTPS Content Delivery using ARLs)",
    "Log Delivery Service",
    "Site Acceleration",
    "Web Application Accelerator",
    "EdgeScape",
    "Security",
    "NetStorage"
]

View password policy for a user profile

Return the password policy for the current account. The current account is determined by the tokens in your API client. Users can run this operation to modify their own profile’s password policy. Administrators who modify a user’s profile should run the View password policy operation.

GET /identity-management/v2/user-profile/common/password-policy

Status 200 application/json

Object type: PasswordPolicy

Download schema: PortalPasswordClass.json

Response body:

{
    "pwclass": "aka90",
    "minLength": 8,
    "minLetters": 1,
    "minDigits": 1,
    "caseDif": 0,
    "minNonAlpha": 0,
    "maxRepeating": 2,
    "minReuse": 4,
    "rotateFrequency": 90
}

View contact types for a user profile

List all the possible contact types that Akamai supports. Use the values from this operation to add or update a user’s contactType. Users can run this operation to modify their own profile’s contact types. Administrators who modify a user’s profile should run the View contact types operation.

GET /identity-management/v2/user-profile/common/contact-types

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "Billing",
    "Technical Decision Maker",
    "Business Decision Maker",
    "Security"
]

View supported countries for a user profile

Return all the possible countries that Akamai supports. Use the values from this operation to add or update a user’s country information. Users can run this operation to set their country in their own profile. Administrators who modify a user’s profile should run the View supported countries operation.

GET /identity-management/v2/user-profile/common/countries

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "Lao People's Democratic Republ",
    "Greece",
    "Greenland",
    "Grenada",
    "Tanzania, United Republic of",
    "Thailand",
    "Togo",
    "Tokelau",
    "Tonga",
    "Djibouti",
    "Dominica",
    "Christmas Island",
    "Cocos (Keeling) Islands",
    "Colombia",
    "Comoros",
    "Curacao"
]

View states for a user profile

Returns country states. Users can run this operation to set their state in their own profile. Administrators who modify a user’s profile should run the View states operation.

GET /identity-management/v2/user-profile/common/countries/{country}/states

Sample: /identity-management/v2/user-profile/common/countries/canada/states

Parameter Type Sample Description
URL path parameters
country String canada Can be set to any country name, but only returns lists of states and provinces for USA and Canada.

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "AB",
    "BC",
    "PQ",
    "NS",
    "NT",
    "NU",
    "QC",
    "YK",
    "NB",
    "MB",
    "PE",
    "TBD",
    "NF",
    "SK",
    "ON"
]

  1. Run the View supported countries for a user profile operation.

  2. Choose a value from the response array and assign it as country URL parameter.

  3. Make a GET request to /identity-management/v2/user-profile/common/countries/{country}/states.

The response is a list of states or provinces.

View timeout policies for a user profile

Lists all the possible session timeout policies that Akamai supports. Use the values from this operation to set the sessionTimeout for a user. The name for each timeout period is in minutes, and the time value is in seconds. Users can run this operation to modify their own profile’s timeout policy. Administrators who modify a user’s profile should run the View timeout policies operation.

GET /identity-management/v2/user-profile/common/timeout-policies

Status 200 application/json

Object type: TimeoutPolicy

Download schema: ListOfSessionTimeoutPolicy.json

Response body:

[
    {
        "name": "after15Minutes",
        "value": 900
    },
    {
        "name": "after30Minutes",
        "value": 1800
    },
    {
        "name": "after45Minutes",
        "value": 2700
    },
    {
        "name": "after1Hour",
        "value": 3600
    },
    {
        "name": "after2Hours",
        "value": 7200
    },
    {
        "name": "after4Hours",
        "value": 14400
    },
    {
        "name": "after18Hours",
        "value": 64800
    }
]

View languages for a user profile

List all the possible languages Akamai supports. Use the values from this API to set the preferred language for a user. Users should see Control Center in the language you set for them. Users can run this operation to set their own profile’s preferred language. Administrators who modify a user’s profile should run the View languages operation.

GET /identity-management/v2/user-profile/common/supported-languages

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "Deutsch",
    "English",
    "Espa\u00f1ol",
    "Espa\u00f1ol (Espa\u00f1a)",
    "Fran\u00e7ais",
    "Italiano",
    "Portugu\u00eas",
    "\u4e2d\u6587 (\u7b80\u4f53)",
    "\u4e2d\u6587 (\u7e41\u9ad4)",
    "\u65e5\u672c\u8a9e",
    "\ud55c\uad6d\uc5b4"
]

View time zones for a user profile

List all time zones Akamai supports. Time zones are in ISO 8601 format. Use the values from this operation to set the timeZone for a user. Users can run this operation to modify their own profile’s time zone. Administrators who modify a user’s profile should run the View time zones operation.

GET /identity-management/v2/user-profile/common/timezones

Status 200 application/json

Object type: TimeZone

Download schema: ListOfTimeZones.json

Response body:

[
    {
        "timezone": "Asia/Rangoon",
        "description": "Asia/Rangoon GMT+6",
        "offset": "+6",
        "posix": "Asia/Rangoon"
    },
    {
        "timezone": "Australia/Sydney",
        "description": "Australia/Sydney GMT+10",
        "offset": "+10",
        "posix": "Australia/Sydney"
    },
    {
        "timezone": "Etc/GMT+3",
        "description": "Etc/GMT+3",
        "offset": "+3",
        "posix": "Etc/GMT-3"
    }
]

View products for a user profile

Return all products a user can subscribe to and receive notifications for on the account. The account is determined by the tokens in your API client. Users can run this operation to modify the set of products for which they receive notifications. Administrators who modify a user’s profile should run the View products operation.

GET /identity-management/v2/user-profile/common/notification-products

Status 200 application/json

Download schema: ListOfString.json

Response body:

[
    "EdgeComputing for Java",
    "Streaming",
    "Enhanced DNS",
    "Site Delivery",
    "Secure FreeFlow (HTTPS Content Delivery using ARLs)",
    "Log Delivery Service",
    "Site Acceleration",
    "Web Application Accelerator",
    "EdgeScape",
    "Security",
    "NetStorage"
]

Data

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

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.

Group

Encapsulates information about a group.

Download schema: GroupResponse.json

Sample GET response:

{
    "groupId": 12345,
    "groupName": "TopLevelGroup",
    "createdDate": "2012-04-28T00:00:00.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2012-04-28T00:00:00.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "edit": true,
        "delete": false
    },
    "subGroups": [
        {
            "groupId": 11111,
            "groupName": "First Level SubGroup",
            "createdDate": "2013-10-29T19:05:52.000Z",
            "createdBy": "johndoe",
            "modifiedDate": "2017-07-25T22:30:20.000Z",
            "modifiedBy": "lionelmessi",
            "parentGroupId": 12345,
            "actions": {
                "edit": true,
                "delete": false
            },
            "subGroups": [
                {
                    "groupId": 123456,
                    "groupName": "Second Level SubGroup",
                    "createdDate": "2017-07-25T22:30:47.000Z",
                    "createdBy": "Company",
                    "modifiedDate": "2017-07-25T22:30:47.000Z",
                    "modifiedBy": "Company",
                    "parentGroupId": 11111,
                    "actions": {
                        "edit": true,
                        "delete": false
                    },
                    "subGroups": []
                }
            ]
        }
    ]
}

Group members

Member Type Required Description
Group: Encapsulates information about a group.
actions Group.actions ○ Encapsulates permissions available to the user for this group. This data is available when you specify the actions parameter of the same name, not to be confused with the action parameter, which applies to the Set two-factor authentication operation.
createdBy String ○ Read-only. The username of the person who created the group.
createdDate String ○ Read-only. ISO 8601 timestamp indicating when the group was originally created.
groupId Integer ○ Read-only. Unique identifier for each group.
groupName String ○ The name you supply for the group.
modifiedBy String ○ Read-only. The username of the last person to edit the group.
modifiedDate String ○ Read-only. ISO 8601 timestamp indicating when the group was last updated.
parentGroupId Integer ○ Read-only. For nested groups, identifies the parent group to which the current group belongs.
subGroups Object ○ Array of nested Group objects.
Group.actions: Encapsulates permissions available to the user for this group. This data is available when you specify the actions parameter of the same name, not to be confused with the action parameter, which applies to the Set two-factor authentication operation.
delete Boolean ○ Indicates whether the user can remove items from the group.
edit Boolean ○ Indicates whether the user can modify items in the group.

Property

Encapsulates information about a property.

Download schema: PropertyResponse.json

Sample GET response:

{
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "doe.john@example.com",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "doe.john@example.com",
    "groupName": "Sales Team",
    "groupId": 45678,
    "arlConfigFile": "abc-dn123-abcde.akamaiorigin.net.xml",
    "propertyId": 9678999,
    "propertyName": "abc-dn123-abcde.akamaiorigin.net"
}

Property members

Member Type Required Description
Property: Encapsulates information about a property.
arlConfigFile String ✓ The configuration file. The arlConfigFile is the same as the propertyName with an xml extension.
createdBy String ✓ Read-only. The username of the person who created the property.
createdDate String ✓ Read-only. ISO 8601 timestamp indicating when the property was originally created.
groupId Integer ✓ Read-only. Unique identifier for each group.
groupName String ✓ The name you supply for the group.
modifiedBy String ✓ Read-only. The username of the last person to edit the property.
modifiedDate String ✓ Read-only. ISO 8601 timestamp indicating when the property was last updated.
propertyId Integer ✓ Read-only. Unique identifier for each property.
propertyName String ✓ The name you supply for the property.

Resource

Encapsulates information about resources.

Download schema: ResourceItem.json

Sample GET response:

[
    {
        "resourceId": 111111,
        "resourceType": "arlfile",
        "resourceName": "abc-dn123-abcde.akamaiorigin.net.xml",
        "modifiedDate": "2017-09-07T17:00:58.000Z"
    },
    {
        "resourceId": 8988898,
        "resourceType": "cpcode",
        "resourceName": "mycpcodeexample(123456)",
        "modifiedDate": "2017-04-24T16:19:27.000Z"
    }
]

Resource members

Member Type Required Description
Resource: Encapsulates information about resources.
modifiedDate String ○ Read-only. ISO 8601 timestamp indicating when the resource was last updated.
resourceId Integer ○ Read-only. Unique identifier for each resource.
resourceName String ○ The name you supply for the resource.
resourceType Enumeration ○ The type of the resource, either cname, arlfile, cpcode, storagegroup, fpdomain, or edns.

User

Encapsulates information about each user.

Download schema: UserResponse.json, CreateUserRequest.json

Sample GET response:

[
    {
        "uiIdentityId": "A-B-123456",
        "firstName": "John",
        "lastName": "Doe",
        "uiUserName": "johndoe",
        "email": "john.doe@mycompany.com",
        "accountId": "1-123A",
        "lastLoginDate": "2016-01-13T17:53:57Z",
        "tfaEnabled": true,
        "tfaConfigured": true,
        "isLocked": false,
        "actions": {
            "resetPassword": true,
            "delete": true,
            "edit": true,
            "apiClient": true,
            "thirdPartyAccess": true,
            "isCloneable": true,
            "editProfile": true,
            "canEditTFA": false
        },
        "authGrants": [
            {
                "groupId": 12345,
                "roleId": 12,
                "groupName": "mygroup",
                "roleName": "admin",
                "roleDescription": "This is a new role that has been created to",
                "isBlocked": false
            }
        ]
    }
]

User members

Member Type GET POST Description
User: Encapsulates information about each user.
actions User.actions ○ ✗ Encapsulates permissions available to the user for this group. This data is available when you specify the actions parameter of the same name, not to be confused with the action parameter that applies to the Set two-factor authentication operation.
address String ✗ ○ The user’s street address.
authGrants User.authGrants[] ○ ○ A user’s role assignments, per group. If you provide this member in a POST request, don’t include the cloneFrom member in the request too.
city String ○ ○ The user’s city.
cloneFrom String ✗ ○ The username to clone a user’s authGrants from. If you provide this member in a POST request, don’t include the authGrants member in the request too.
contactType String ○ ○ To help characterize the user, the value can be any that are available from the View contact types operation.
country String ✓ ○ As part of the user’s location, the value can be any that are available from the View supported countries operation.
email String ✓ ○ The user’s email address.
firstName String ✓ ○ The user’s first name.
isLocked Boolean ○ ✗ The user’s lock status.
jobTitle String ○ ○ The user’s position at your company.
lastLoginDate String ○ ✗ Read-only. ISO 8601 time stamp indicating when the user last logged in.
lastName String ✓ ○ The user’s surname.
mobilePhone String ○ ○ The user’s mobile phone number, represented as a ten-digit integer within a string.
notifications User.notifications ○ ✗ The notification emails the user receives for products.
passwordExpiryDate String ○ ✗ Read-only. The date a user’s password expires.
phone String ✓ ○ The user’s main phone number, represented as a ten-digit integer within a string.
preferredLanguage String ○ ○ The value can be any that are available from the View languages operation.
secondaryEmail String ○ ○ The user’s secondary email address.
sessionTimeOut Integer ○ ○ The number of seconds it takes for the user’s Control Center session to time out if there hasn’t been any activity. This corresponds to the value output of the View timeout policies operation.
state String ○ ○ The user’s state.
street String ○ ✗ The user’s street address.
tfaEnabled Boolean ✗ ○ When enabled, two-factor authentication confirms the user’s identity.
timezone String ○ ○ The user’s time zone. The value can be any that are available from the View time zones operation.
timeZone String ✗ ○ The user’s time zone, any of the values available from the View time zones operation.
uiIdentityId String ✓ ✗ Read-only. A unique identifier for a user’s profile, which corresponds to a user’s actual profile or client ID.
uiUserName String ○ ✗ A user’s loginId. Typically, a user’s email address.
zipCode String ○ ○ The user’s five-digit ZIP code, represented as a string.
User.actions: Encapsulates permissions available to the user for this group. This data is available when you specify the actions parameter of the same name, not to be confused with the action parameter that applies to the Set two-factor authentication operation.
apiClient Boolean ✓ ✗ Allows the administrator to create an API client.
delete Boolean ✓ ✗ Indicates whether the user is deletable.
edit Boolean ✓ ✗ Indicates whether the user is editable.
isCloneable Boolean ✓ ✗ If true an administrator can create a new user with the same permissions as this user.
resetPassword Boolean ✓ ✗ Allows an administrator to send a user a password by email or see a one-time token.
thirdPartyAccess Boolean ✓ ✗ Allows the administrator to manage extended access.
User.authGrants[]: A user’s role assignments, per group. If you provide this member in a POST request, don’t include the cloneFrom member in the request too.
groupId Integer ○ ✗ Read-only. Unique identifier for each group.
groupName String ○ ✗ The name you supply for the group.
isBlocked Boolean ○ ✗ Indicates whether a user’s access is blocked for a group.
roleDescription String ○ ✗ Descriptive text for the role.
roleId Integer ○ ✗ Read-only. Unique identifier for each role.
roleName String ○ ✗ The name you supply for the role.
User.notifications: The notification emails the user receives for products.
enableEmailNotifications Boolean ○ ✗ When set to false, suspend email notifications. When set to true, allow email notifications.
options User.notifications.options ○ ✗ The types of notification emails the user receives.
User.notifications.options: The types of notification emails the user receives.
newUserNotification Boolean ○ ✗ Send emails to group administrators when new users are created.
passwordExpiry Boolean ○ ✗ Send emails regarding password expiration.
proactive Array ○ ✗ Lists products for which the user receives notification emails about service issues.
upgrade Array ○ ✗ Lists products for which the user receives notification emails about upgrades.

Role

A role that includes granted roles.

Download schema: RoleWithGrantedRoles.json

Sample GET response:

{
    "roleId": 123456,
    "roleName": "Security View Only",
    "roleDescription": "This role will allow you to look at the security reports",
    "type": "custom",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "john.doe@mycompany.com",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "john.doe@mycompany.com",
    "actions": {
        "edit": false,
        "delete": false
    },
    "users": [
        {
            "uiIdentityId": "A-B-12345",
            "firstName": "John",
            "lastName": "Doe",
            "accountId": "1-2ABC",
            "email": "john.doe@mycompany.com",
            "lastLoginDate": "2017-08-03T21:15:27.000Z"
        },
        {
            "uiIdentityId": "1-2ABCD",
            "firstName": "Jane",
            "lastName": "Lane",
            "accountId": "1-7XYZ",
            "email": "lane.jane@mycompany.com",
            "lastLoginDate": "2016-09-07T00:00:00.000Z"
        }
    ],
    "grantedRoles": [
        {
            "grantedRoleId": 12345,
            "grantedRoleName": "SecurityViewOnly",
            "grantedRoleDescription": "Security View Only"
        }
    ]
}

Role members

Member Type Required Description
Role: A role that includes granted roles.
actions Role.actions ○ Encapsulates permissions available to the user for this group. This data is available when you specify the actions parameter of the same name, not to be confused with the action parameter that applies to the Set two-factor authentication operation.
createdBy String ✓ Read-only. The username of the person who created the granted role.
createdDate String ✓ Read-only. ISO 8601 timestamp indicating when the granted role was originally created.
grantedRoles Role.grantedRoles[] ○ Within the role, there’s a list of granted roles, giving the user access to objects in a group.
modifiedBy String ✓ Read-only. The username of the last person to edit the granted role.
modifiedDate String ✓ Read-only. ISO 8601 timestamp indicating when the granted role was last updated.
roleDescription String ✓ Descriptive text for the role.
roleId Integer ✓ Read-only. Unique identifier for each role.
roleName String ✓ The name you supply for the role.
type Enumeration ✓ Indicates whether it’s a standard role provided by Akamai or a custom role for the account.
users Role.users[] ○ List of users who share the same role.
Role.actions: Encapsulates permissions available to the user for this group. This data is available when you specify the actions parameter of the same name, not to be confused with the action parameter that applies to the Set two-factor authentication operation.
delete Boolean ○ Indicates whether the user can remove items from the group.
edit Boolean ○ Indicates whether the user can modify items in the group.
Role.grantedRoles[]: Within the role, there’s a list of granted roles, giving the user access to objects in a group.
grantedRoleDescription String ○ The description you supply for the granted role.
grantedRoleId Integer ✓ Read-only. Unique identifier for each granted role.
grantedRoleName String ✓ The name you supply for the granted role.
Role.users[]: List of users who share the same role.
accountId String ✓ Read-only. Unique identifier for each account.
email String ✓ The user’s email address.
firstName String ✓ The user’s first name.
lastLoginDate String ○ Read-only. ISO 8601 timestamp indicating when the user last logged in.
lastName String ✓ The user’s surname.
uiIdentityId String ✓ Read-only. A unique identifier for a user’s profile, which corresponds to a user’s actual profile or client ID.

GrantableRole

Encapsulates identifiers for granted roles.

Download schema: GrantedRole.json

Sample GET response:

[
    {
        "grantedRoleId": 2051,
        "grantedRoleName": "WAF Strict WhiteList",
        "grantedRoleDescription": "WAF Strict WhiteList"
    },
    {
        "grantedRoleId": 1032,
        "grantedRoleName": "License Delivery Configurations - Manage",
        "grantedRoleDescription": "Manage License Delivery Configurations"
    },
    {
        "grantedRoleId": 2063,
        "grantedRoleName": "View Audience Analytics Reports",
        "grantedRoleDescription": "View Audience Analytics Reports"
    },
    {
        "grantedRoleId": 77852,
        "grantedRoleName": "RealUserMonitoring - View Only",
        "grantedRoleDescription": "View Real User Monitoring"
    },
    {
        "grantedRoleId": 32,
        "grantedRoleName": "Enhanced DNS - All privileges (add/edit/view)",
        "grantedRoleDescription": "Add/Edit/View Enhanced DNS - All privileges"
    }
]

GrantableRole members

Member Type Required Description
GrantableRole: Encapsulates identifiers for granted roles.
grantedRoleDescription String ○ The description you supply for the granted role.
grantedRoleId Integer ○ Read-only. Unique identifier for each granted role.
grantedRoleName String ○ The name you supply for the granted role.

Notifications

Encapsulates the types of email notifications you can receive.

Download schema: NotificationsResponse.json

Sample PUT response:

{
    "enableEmailNotifications": true,
    "options": {
        "upgrade": [
            "NetStorage",
            "Other Upgrade Notifications (Planned)"
        ],
        "proactive": [
            "EdgeScape",
            "EdgeSuite (HTTP Content Delivery)"
        ],
        "passwordExpiry": true,
        "newUserNotification": true
    }
}

Notifications members

Member Type Required Description
Notifications: Encapsulates the types of email notifications you can receive.
enableEmailNotifications Boolean ○ If true, suspend email notifications. If false, send email notifications.
options Notifications.options ○ Specific notification types users can subscribe to.
Notifications.options: Specific notification types users can subscribe to.
newUserNotification Boolean ○ Send emails to group admins regarding new user creation.
passwordExpiry Boolean ○ Send emails regarding password expiration.
proactive Array ○ A list of products subscribed to for proactive notification emails.
upgrade Array ○ A list of products subscribed to for upgrade notification emails.

MoveGroup

Describes the request body to move one group under another group, or to move a property from one group to another.

Download schema: MoveGroupRequest.json

Sample POST request:

{
    "sourceGroupId": 12345,
    "destinationGroupId": 54321
}

MoveGroup members

Member Type Required Description
MoveGroup: Describes the request body to move one group under another group, or to move a property from one group to another.
destinationGroupId Integer ✓ Identifies the group to which you want to move the property.
sourceGroupId Integer ✓ Identifies the group from which you want to move the property.

RotatePassword

Uses the old password to authenticate you are who you say you are when you update your password. Includes the new password.

Download schema: ChangePasswordRequest.json

Sample POST request:

{
    "currentPassword": "abcbd",
    "newPassword": "abcdg"
}

RotatePassword members

Member Type Required Description
RotatePassword: Uses the old password to authenticate you are who you say you are when you update your password. Includes the new password.
currentPassword String ✓ Your existing password.
newPassword String ✓ Your new password.

PasswordPolicy

Encapsulates all information for a password policy.

Download schema: PortalPasswordClass.json

Sample GET response:

{
    "pwclass": "aka90",
    "minLength": 8,
    "minLetters": 1,
    "minDigits": 1,
    "caseDif": 0,
    "minNonAlpha": 0,
    "maxRepeating": 2,
    "minReuse": 4,
    "rotateFrequency": 90
}

PasswordPolicy members

Member Type Required Description
PasswordPolicy: Encapsulates all information for a password policy.
caseDif Integer ✓ The number of characters that at minimum, must be in a different case. For example, a value of 1 means at least one letter must be uppercase if the rest are lowercase.
maxRepeating Integer ✓ The maximum allowed number of repeating characters.
minDigits Integer ✓ The minimum number of digits in a password.
minLength Integer ✓ The minimum length of a password.
minLetters Integer ✓ The minimum number of letters in a password.
minNonAlpha Integer ✓ The minimum number of non-alphabetic characters in a password.
minReuse Integer ✓ The minimum number of previous passwords to retain to prevent password reuse.
pwclass String ✓ A unique identifier for a password policy.
rotateFrequency Integer ○ The number of days a password is valid.

TimeoutPolicy

Specifies session timeout policy options that can be assigned to each user.

Download schema: SessionTimeoutPolicy.json

Sample GET:

[
    {
        "name": "after15Minutes",
        "value": 900
    },
    {
        "name": "after30Minutes",
        "value": 1800
    },
    {
        "name": "after45Minutes",
        "value": 2700
    },
    {
        "name": "after1Hour",
        "value": 3600
    },
    {
        "name": "after2Hours",
        "value": 7200
    },
    {
        "name": "after4Hours",
        "value": 14400
    },
    {
        "name": "after18Hours",
        "value": 64800
    }
]

TimeoutPolicy members

Member Type Required Description
TimeoutPolicy: Specifies session timeout policy options that can be assigned to each user.
name String ✓ The unit of time in which the timeout is measured. The timeout is measured in seconds.
value Integer ✓ The number of seconds until the timeout.

TimeZone

Specifies time zones that can be assigned to each user.

Download schema: TimeZone.json

Sample GET:

[
    {
        "timezone": "Asia/Rangoon",
        "description": "Asia/Rangoon GMT+6",
        "offset": "+6",
        "posix": "Asia/Rangoon"
    },
    {
        "timezone": "Australia/Sydney",
        "description": "Australia/Sydney GMT+10",
        "offset": "+10",
        "posix": "Australia/Sydney"
    },
    {
        "timezone": "Etc/GMT+3",
        "description": "Etc/GMT+3",
        "offset": "+3",
        "posix": "Etc/GMT-3"
    }
]

TimeZone members

Member Type Required Description
TimeZone: Specifies time zones that can be assigned to each user.
description String ✓ The description of a time zone, including the GMT +/-.
offset String ○ The time zone offset from GMT.
posix String ○ The time zone posix.
timezone String ✓ The time zone ID.

Errors

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

Error responses

This API adheres to the HTTP Problem Details standard.

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation was successful.
201 Resource successfully created.
204 Successfully processed request. Empty/no response body.
400 Bad Request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
405 Method not supported.
409 Conflict with current state of resource.
415 Unsupported media type.
500 Internal server error.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable.
507 Insufficient storage for size of request. Try again later.