Roles

Get User's Role Assignments

GET roleAssignments/users/{userId}
Method GET
Endpoint am/v2/roleAssignments/users/{userId}
Headers Authorization
Path Parameters userId
Query Parameters resourceId, resourceType, offset, limit
Body Parameters Not applicable

This method returns all active role assignments for a specific user. It shows information about their role and what resources they can access.


Sample curl request

Copy 
curl -X GET 'https://api.equinix.com/am/v2/roleAssignments/users/972239?resourceId=563d7790-8083-4af0-8df7-e115b768365b&resourceType=ORGANIZATION'
-H 'authorization: Bearer qwErtY8zyW1abcdefGHI'

Query parameters

Parameter
Description
resourceId string
REQUIRED		 Resource ID.
resourceType string
REQUIRED		 Resource type.
Possible values:
  • PROJECT
  • ORGANIZATION
offset integer
OPTIONAL		 Index of the first item returned in the response.
Default: 0
limit integer
OPTIONAL		 Maximum number of items returned per page.
Default: 50
Limit: 500

Sample response

Copy 
{
    "data": [
        {
            "id": "212f8c2a-12f6-4387-be5c-476e9cbbc7f6",
            "user": {
                "userId": "972239",
                "firstName": "John",
                "lastName": "Doe",
                "userName": "johndoe1",
                "email": "johndoe@corp.com"
            },
            "role": {
                "name": "role/project.viewer",
                "displayName": "Project Viewer",
                "description": "Project View - Read capability on resources within project"
            },
            "resource": {
                "id": "563d7790-8083-4af0-8df7-e115b768365b",
                "type": "ORGANIZATION"
            },
            "constraints": [
                {
                    "name": "BILLING_ACCOUNT",
                    "values": [
                        "159920",
                        "592578"
                    ],
                    "operator": "IN"
                }
            ],
            "inheritedFromResource": {
                "id":"563d7790-8083-4af0-8df7-e115b768365b"
                "type": "ORGANIZATION"
            },
            "createdDate": "2023-09-26",
            "createdBy": "1c8285d1-5fca-44c3-864e-01c30d92c560",
            "lastUpdatedDate": "2023-09-26",
            "lastUpdatedBy": "1c8285d1-5fca-44c3-864e-01c30d92c560"
        },
        {
            "id": "6b4068af-db64-4eb0-a0e3-57c1558878b1",
            "user": {
                "userId": "972239",
                "firstName": "TONNY",
                "lastName": "STARK",
                "userName": "tonnystark",
                "email": "TONY@TONY.co"
            },
            "role": {
                "name": "SmartHand Support Plan Notification",
                "displayName": "SmartHand Support Plan Notification",
                "description": "Subscribe for SmartHand Support Plan Notification"
            },
            "resource": {
                "id": "563d7790-8083-4af0-8df7-e115b768365b",
                "type": "ORGANIZATION"
            },
            "constraints": [
                {
                    "name": "BILLING_ACCOUNT",
                    "values": [
                        "570121",
                        "161094",
                        "156781"
                    ],
                    "operator": "IN"
                }
            ],
            "inheritedFromResource": {},
            "createdDate": "2023-09-26",
            "createdBy": "1c8285d1-5fca-44c3-864e-01c30d92c560",
            "lastUpdatedDate": "2023-09-26",
            "lastUpdatedBy": "1c8285d1-5fca-44c3-864e-01c30d92c560"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 500,
        "total": 2
        "next": "/roleAssignments/users/972239 resourceId=563d7790-8083-4af0-8df7-e115b768365b&resourceType=ORGANIZATION&limit=1&offset=2",
        "previous": "/roleAssignments/users/972239 resourceId=563d7790-8083-4af0-8df7-e115b768365b&resourceType=ORGANIZATION&limit=1&offset=0"
    }
}

Response payload body description

Parameter
Description
data array[object]
 Data set containing projects information.
Id string
REQUIRED
 Resource identifier
Example: 212f8c2a-12f6-4387-be5c-476e9cbbc7f6
user object
 User details.
userId string
 User identifier.
Example: 972239
firstName string
 Legal first name or given name.
Example: John
lastName string
 Legal last name, surname, or family name.
Example: Doe
userName string
 Username of the portal user.
Example: johndoe1
email string
 Primary email address.
Example: johndoe@corp.com
role object
REQUIRED
 Role details.
name string
REQUIRED
 Name of the user's role.
Example: role/project.viewer
displayName string
 Displayed name of the user's role.
Example: Project Viewer
description string
 Description of the user's role.
Example: Project View - Read capability on resources within project
resource object
REQUIRED
 Resource details.
id string
 Identifier of the resource.
Example: 563d7790-8083-4af0-8df7-e115b768365b
type string
 Resource type.
Possible values:
  • PROJECT
  • ORGANIZATION
inheritedFromResource object
 Permission or role is inherited from another resource.


Permission or role is received from another, usually higher-level, resource. It refers to where a role or permission originally comes from in a hierarchical structure.

id string
 Identifier of the resource.
Example: 563d7790-8083-4af0-8df7-e115b768365b
type string
 Resource type.
Possible values:
  • PROJECT
  • ORGANIZATION
constraints array[object]
REQUIRED
 Constraints.
name string
REQUIRED
 Resource type.
Possible values:
  • IBX
  • CAGE
  • BILLING ACCOUNT
values array[string]
REQUIRED
 Values of the constraints.
operator string
REQUIRED
 Operator that defines a condition for the constraint.
Possible values:
  • IN
createdDate string
REQUIRED
 Date of user's role creation.
Example: 2023-09-26
createdBy string
REQUIRED
 The Id of user.
Example: 1c8285d1-5fca-44c3-864e-01c30d92c560
lastUpdateDate string
 Date of user's role update.
Example: 2023-09-26
lastUpdateBy string
 Id of the user.
Example: 1c8285d1-5fca-44c3-864e-01c30d92c560
pagination object
 Data set pagination information.
offset integer
REQUIRED
 Index of the first item returned in the response.
limit integer
REQUIRED
 Maximum number of items returned per page.
total integer
REQUIRED
 Total number of items.
previous integer
 Previous data page URL.
Example: am/v2/roleAssignments/users/{userId}?offset=0&limit=20
next integer
 Next data page URL.
Example: /am/v2/roleAssignments/users/{userId}?offset=10&limit=20

Get Role Assignments by Role ID

GET roleAssignments/roles/{roleId}
Method GET
Endpoint am/v2/roleAssignments/roles/{roleId}
Headers Authorization
Path Parameters roleId
Query Parameters resourceId, resourceType, offset, limit
Body Parameters Not applicable

This method returns all active role assignments based on specific role identifier.


Sample curl request

Copy 
curl -X GET 'https://api.equinix.com/am/v2/roleAssignments/roles/{roleId}?resourceId=563d7790-8083-4af0-8df7-e115b768365b&resourceType=ORGANIZATION'
-H 'authorization: Bearer qwErtY8zyW1abcdefGHI'

Query parameters

Parameter
Description
resourceId string
REQUIRED		 Resource ID.
resourceType string
REQUIRED		 Resource type.
Possible values:
  • PROJECT
  • ORGANIZATION
offset integer
OPTIONAL		 Index of the first item returned in the response.
Default: 0
limit integer
OPTIONAL		 Maximum number of items returned per page.
Default: 50
Limit: 500

Sample response

Copy 
{
    "data": [
        {
            "id": "212f8c2a-12f6-4387-be5c-476e9cbbc7f6",
            "user": {
                "userId": "972239",
                "firstName": "John",
                "lastName": "Doe",
                "userName": "johndoe1",
                "email": "johndoe@corp.com"
            },
            "role": {
                "name": "role/project.viewer",
                "displayName": "Project Viewer",
                "description": "Project View - Read capability on resources within project"
            },
            "resource": {
                "id": "563d7790-8083-4af0-8df7-e115b768365b",
                "type": "ORGANIZATION"
            },
            "constraints": [
                {
                    "name": "BILLING_ACCOUNT",
                    "values": [
                        "159920",
                        "592578"
                    ],
                    "operator": "IN"
                }
            ],
            "inheritedFromResource": {
                "id":"563d7790-8083-4af0-8df7-e115b768365b"
                "type": "ORGANIZATION"
            },
            "createdDate": "2023-09-26",
            "createdBy": "1c8285d1-5fca-44c3-864e-01c30d92c560",
            "lastUpdatedDate": "2023-09-26",
            "lastUpdatedBy": "1c8285d1-5fca-44c3-864e-01c30d92c560"
        },
        {
            "id": "6b4068af-db64-4eb0-a0e3-57c1558878b1",
            "user": {
                "userId": "972239",
                "firstName": "TONNY",
                "lastName": "STARK",
                "userName": "tonnystark",
                "email": "TONY@TONY.co"
            },
            "role": {
                "name": "SmartHand Support Plan Notification",
                "displayName": "SmartHand Support Plan Notification",
                "description": "Subscribe for SmartHand Support Plan Notification"
            },
            "resource": {
                "id": "563d7790-8083-4af0-8df7-e115b768365b",
                "type": "ORGANIZATION"
            },
            "constraints": [
                {
                    "name": "BILLING_ACCOUNT",
                    "values": [
                        "570121",
                        "161094",
                        "156781"
                    ],
                    "operator": "IN"
                }
            ],
            "inheritedFromResource": {},
            "createdDate": "2023-09-26",
            "createdBy": "1c8285d1-5fca-44c3-864e-01c30d92c560",
            "lastUpdatedDate": "2023-09-26",
            "lastUpdatedBy": "1c8285d1-5fca-44c3-864e-01c30d92c560"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 500,
        "total": 2
        "next": "/roleAssignments/users/972239 resourceId=563d7790-8083-4af0-8df7-e115b768365b&resourceType=ORGANIZATION&limit=1&offset=2",
        "previous": "/roleAssignments/users/972239 resourceId=563d7790-8083-4af0-8df7-e115b768365b&resourceType=ORGANIZATION&limit=1&offset=0"
    }
}

Response payload body description

Parameter
Description
data array[object]
 Data set containing projects information.
Id string
REQUIRED
 Resource identifier
Example: 212f8c2a-12f6-4387-be5c-476e9cbbc7f6
user object
 User details.
userId string
 User identifier.
Example: 972239
firstName string
 Legal first name or given name.
Example: John
lastName string
 Legal last name, surname, or family name.
Example: Doe
userName string
 Username of the portal user.
Example: johndoe1
email string
 Primary email address.
Example: johndoe@corp.com
role object
REQUIRED
 Role details.
name string
REQUIRED
 Name of the user's role.
Example: role/project.viewer
displayName string
 Displayed name of the user's role.
Example: Project Viewer
description string
 Description of the user's role.
Example: Project View - Read capability on resources within project
resource object
REQUIRED
 Resource details.
id string
 Identifier of the resource.
Example: 563d7790-8083-4af0-8df7-e115b768365b
type string
 Resource type.
Possible values:
  • PROJECT
  • ORGANIZATION
inheritedFromResource object
 Permission or role is inherited from another resource.


Permission or role is received from another, usually higher-level, resource. It refers to where a role or permission originally comes from in a hierarchical structure.

id string
 Identifier of the resource.
Example: 563d7790-8083-4af0-8df7-e115b768365b
type string
 Resource type.
Possible values:
  • PROJECT
  • ORGANIZATION
constraints array[object]
REQUIRED
 Constraints.
name string
REQUIRED
 Resource type.
Possible values:
  • IBX
  • CAGE
  • BILLING ACCOUNT
values array[string]
REQUIRED
 Values of the constraints.
operator string
REQUIRED
 Operator that defines a condition for the constraint.
Possible values:
  • IN
createdDate string
REQUIRED
 Date of user's role creation.
Example: 2023-09-26
createdBy string
REQUIRED
 The Id of user.
Example: 1c8285d1-5fca-44c3-864e-01c30d92c560
lastUpdateDate string
 Date of user's role update.
Example: 2023-09-26
lastUpdateBy string
 Id of the user.
Example: 1c8285d1-5fca-44c3-864e-01c30d92c560
pagination object
 Data set pagination information.
offset integer
REQUIRED
 Index of the first item returned in the response.
limit integer
REQUIRED
 Maximum number of items returned per page.
total integer
REQUIRED
 Total number of items.
previous integer
 Previous data page URL.
Example: am/v2/roleAssignments/users/{userId}?offset=0&limit=20
next integer
 Next data page URL.
Example: /am/v2/roleAssignments/users/{userId}?offset=10&limit=20

Update User Role Assignments

PUT /roleAssignments/{roleAssignmentId}/constraints
Method PUT
URL or End Point /am/v2/roleAssignments/{roleAssignmentId}/constraints
Headers Authorization, Content-Type
Path Parameters roleAssignmentId
Query Parameters Not applicable
Body constraints [{name, values [ ], operator}]

This method updates user's role assignments. Modify constraints based on role assignment. Only an authenticated user with administrator privileges may update user's role assignment. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

Sample curl request

Copy 
curl -X PUT 'https://api.equinix.com/am/v2/roleAssignments//{roleAssignmentId}/constraints'
-H 'content-type: application/json'
-H 'authorization: Bearer qwErtY8zyW1abcdefGHI'
-d '{
    "constraints": [
        {
            "name": "BILLING_ACCOUNT",
            "values": [
                "159920",
                "592578"
            ],
            "operator": "IN"
        }
    ]
}'

Request body description

Parameter
Description
constraints array[object]
REQUIRED
 Constraints.
name string
REQUIRED
 Resource type.
Possible values:
  • IBX
  • CAGE
  • BILLING ACCOUNT
values array[string]
REQUIRED
 Values of the constraints.
operator string
REQUIRED
 Operator that defines a condition for the constraint.
Possible values:
  • IN

A user's role is successfully updated when an HTTP code of 202 is returned.

Delete Role Assignments by IDs

DELETE /roleAssignments
Method DELETE
URL or End Point /am/v2/roleAssignments
Headers Authorization, Content-Type
Path Parameters Not applicable
Query Parameters ids
Body Not applicable

This method remove role assignments with the provided IDs. Only an authenticated user with administrator privileges may update user's role assignment. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

Sample curl request

Copy 
curl -X DEL 'https://api.equinix.com/am/v2/roleAssignments/ids'
-H 'content-type: application/json'
-H 'authorization: Bearer qwErtY8zyW1abcdefGHI'

Request path parameter description

Parameter
Description
ids string
REQUIRED
 Comma-separated list of role assignment ids (uuid).
Example: 212f8c2a-12f6-4387-be5c-476e9cbbc7f6

Role assignments are successfully deleted when an HTTP code of 204 is returned. There is no response body.