User Management

 

Deprecation of Users v1 API

Equinix will be deprecating Users_v1 API by 1st December 2022.
Therefore, we strongly recommend users migrate to Users_v2 API before this date.
For information on the API, see the User Management guide.

If you have any questions, contact Equinix API support @ api-support@equinix.com.

Manage your organizations' portal users with the following use cases.

Create new user

Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating Client ID and Client Secret under Getting Access Token section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk. 

Step 2: Create New User

	POST /users
Method	POST
URL or End Point	/access/v2/users
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	firstName, lastName, companyName, contactDetails [{ type, value }], username, localName, companyLocalName, title, department, timezone, deactivationDateTime, locale

This method creates a new portal user within your organization. Only an authenticated user with administrator privileges may create a new user. 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.

The following screenshots show sample curl requests for these different scenarios:

(A) User creation with minimum required information. Only the minimum required body parameters are passed in this sample request payload.

(B) User creation with all other available and applicable body parameters passed in this sample request payload.

 

All information provided must match the user's valid government-issued identification document.

(A) User creation with minimum required information

For this scenario, you are requesting to create a user profile with the basic information required. The username in this case will default to the user's primary email address. The minimum required information for this scenario is passed in this sample request.

curl -X
POST "https://api.equinix.com/access/v2/users"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "firstName": "John",
  "lastName": "Doe",
  "companyName": "Acme Corporation",
  "contactDetails": [
    {
      "type": "PHONE",
      "value": "+81-987-654-3210"
    },
    {
      "type": "EMAIL",
      "value": "johndoe@corp.com"
    }
  ]
}'

(B) User creation request with all applicable body parameters

In this scenario, you have provided the minimum required information to facilitate user creation, and included additional body parameters which support the following:

• your chosen username
• local name of the user
• local company name
• user's designation
• user's department
• user's timezone
• a future deactivation date for the user profile
• user's preferred language

All available and applicable body parameters are passed in this sample request.

curl -X
POST "https://api.equinix.com/access/v2/users"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "firstName": "John",
  "lastName": "Doe",
  "companyName": "Acme Corporation",
  "contactDetails": [
    {
      "type": "PHONE",
      "value": "+1-987-654-3210"
    },
    {
      "type": "EMAIL",
      "value": "johndoe@corp.com"
    },
    {
      "type": "MOBILE",
      "value": "+1-987-123-4567"
    },
    {
      "type": "SECONDARY_EMAIL",
      "value": "janesmith@corp.com"
    }
  ],
  "username": "johndoe1",
  "localName": "ジョン・ドー",
  "companyLocalName": "アクミー会社",
  "title": "Manager",
  "department": "Procurement",
  "timezone": "Asia/Tokyo",
  "locale": "JA_JP",
  "deactivationDateTime": "2022-01-29T01:10:11Z"
}'

The description of the body parameters is as follows:

Body Parameter name	Mandatory	Type	Example	Applicable Values	Description
firstName	Yes	string	John		Legal first name or given name.   This name must match what is stated on the user's valid government-issued identification document. Limit: 1 - 50 characters.
lastName	Yes	string	Doe		Legal last name, surname, or family name.   This name must match what is stated on the user's valid government-issued identification document. Limit: 1 - 50 characters.
companyName	Yes	string	Acme Corporation		Company associated with the user. Limit: 1 - 100 characters.
contactDetails	Yes	array [objects]			Contact details for the user. Each contact details object contains the following parameters: type, value. It is mandatory to provide a phone number and email address. Only one of each type can be provided. Limit: 2 to 4 objects.
type	Yes	string	PHONE	PHONE, EMAIL, MOBILE, SECONDARY_EMAIL	Defines the contact detail type. Type - Description PHONE - Mandatory phone number. This is the primary contact number. EMAIL - Mandatory email address. This is the primary email address. MOBILE - Mobile phone number. This is the secondary contact number. SECONDARY_EMAIL - Secondary email address.
value	Yes	string	+81-987-654-3210		Value associated with the contact detail type. Phone numbers must be prefixed by '+' country code. For example, +1-987-654-3210 or +1 987 654 3210. Email addresses must follow a valid email format.
username	No	string	johndoe1		Your chosen username.   It is recommended to chose a unique username when creating your user. When a username is not submitted upon creation, it defaults to the user's primary email address. This username cannot be changed. Limit: 8 - 100 characters.
localName	No	string	ジョン・ドー		User's legal name in non-Western characters.   This field is required for official names with non-Western characters, and must match what is stated on the user's valid government-issued identification document. Limit: 1 - 100 characters.
companyLocalName	No	string	アクミー会社		Name of the company in non-Western characters.   This field is required for official company names with non-Western characters. Limit: 1 - 100 characters.
title	No	string	Manager		Job title or designation of new user. Limit: 1 - 50 characters.
department	No	string	Procurement		Department of new user. Limit: 1 - 50 characters.
timezone	No	string	Asia/Tokyo	Click here for applicable values.	User's timezone. Equinix will contact the user in this timezone. Default value: UTC
locale	No	string	JA_JP	Click here for applicable values.	New user's preferred language in the Equinix portal.
deactivationDateTime	No	string	2022-01-29T01:10:11Z		Future deactivation date and time. Provide a date and time (UTC timezone) in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ

A new user is successfully created when an HTTP code of 201 and the following response header are returned. There is no response body.

HTTP Response Header	Description
Location	Location of the user. Example: /users/{username}   This username is important to retrieve, update, or terminate a user. See Users (V2) in the API Reference Section for more information.

Once a new user is created, their status will be "APPROVED", and they may be listed as a notification or technical contact for any future portal requests. Before this newly created user can access the portal and request its services, they must have their permissions assigned and password created by their administrator through the Equinix Customer Portal.

 

If you get “Insufficient permissions” error, contact your Master Administrator.

Copy user permissions

Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating Client ID and Client Secret under Getting Access Token section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk. 

Step 2: Get Source and Target Usernames

2a) Get username
Determine the username of the intended source and target users.

To verify this username belongs to the intended user, proceed to Step 2b.

When you are certain this is the correct username, proceed to Step 3, where this value will be passed in the request body for the following parameter: id.

 

Refer to GET Users under the API Reference section for instructions on how to get all your users. You may skip this step if you know this username.

2b) Verify username
Ensure the user profile details match the details of the intended user.

It is important to ensure this is the correct user whose permissions will be copied.

 

Refer to GET Users {username} under the API Reference section for instructions on how to get your user profile. You may skip this step if you are certain this is the intended user.

Step 3: Copy User Permissions

	POST /users/permissionsCopy
Method	POST
URL or End Point	/access/v2/users/permissionsCopy
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	sourceRegisteredUser, targetRegisteredUsers

This method copies a user's permissions in the portal by an authenticated user with administrator privileges. 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.

 

Only Master Admin and IBX Admin user roles can perform the copy permission function.
This function copies permissions from identified user to the selected user. You cannot undo this action.
Ensure the user whose permissions you want to copy is correct.

As a	You can	You cannot
Master Admin	[As a Master Admin you can] copy all permissions of: Master Admin to Master Admin Master Admin to IBX Admin Master Admin to User	N/A
IBX Admin	[As a IBX Admin you can] only copy permissions from your assigned IBXs.   Common permissions required between IBX admin and its user - access to specific IBX.	[As a IBX Admin you cannot] copy permissions of: Master Admin to User Master Admin to IBX Admin IBX Admin to Master Admin User to Master Admin Equinix Fabric and Network ports from User A to User B Scenarios - no common permissions between IBX Admin and its user: IBX Admin manages user A. Only user A has permissions assigned to TY1 IBX. When IBX Admin tries to copy permissions from user A to user B the operation fails. IBX Admin has access to SG1 IBX only, but user A has access to both SG1 and SG2. When IBX Admin tries to copy permissions from user A to user B, only SG1 is copied, ignoring SG2 to user B.
	[As a IBX Admin you can] only copy permissions from user role to user role: User A to User B User B to User A	[As a IBX Admin you cannot] copy permissions of IBX Admin to IBX Admin.

 

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

The following screenshot shows a sample curl request for this method.

curl -X
POST "https://api.equinix.com/access/v2/users/permissionsCopy"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "sourceRegisteredUser": "johndoe",
  "targetRegisteredUsers": [
      "targetusername1"
    ]
}'

The description of the body parameters is as follows:

Body Parameter name	Mandatory	Type	Example	Applicable Values	Description
sourceRegisteredUser	Yes	array[strings]	johndoe		The name of the registered user from whom you want to copy permissions.
targetRegisteredUsers	Yes	array[strings]	targetusername1	USERNAME	The name of the registered user to whom you want to copy permissions. Default value: USERNAME   The current limit is one user - more users may impact performance and risk of timeouts for solutions with a high number of IBXs and permissions.

{
    "successes": [
        "targetusername1"
    ],
    "failures": [
        {
            "errors": []
        }
    ]
}

The description of the response payload is as follows:

Field name	Type	Example	Description
successes	array[strings]	targetusername1	List of usernames with the successfully copied permissions.
failures	array[objects]		Array of generated failures.
errors	array[objects]		Indicates the errors linked to this generated failure.

 

If you get “Insufficient permissions” error, contact your Master Administrator.

Terminate user

Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating Client ID and Client Secret under Getting Access Token section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk. 

Step 2: Get Username

2a) Get username
Determine the username of the intended user.

To verify this username belongs to the intended user, proceed to Step 2b.

When you are certain this is the correct username, proceed to Step 3, where this value will be passed in the request body for the following parameter: id.

 

Refer to GET Users under the API Reference section for instructions on how to get all your users. You may skip this step if you know this username.

2b) Verify username
Ensure the user profile details match the details of the intended user.

As termination is permanent and cannot be undone, it is important to ensure this is the correct user whose profile, permissions, and physical access to the IBX data center will be terminated.

 

Refer to GET Users {username} under the API Reference section for instructions on how to get your user profile. You may skip this step if you are certain this is the intended user.

Step 3: Terminate User

	POST /users/accessChange
Method	POST
URL or End Point	/access/v2/users/accessChange
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	id, idType, action, reason

This method terminates a user in the portal by an authenticated user with administrator privileges. 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.

 

User termination deletes the user profile and their access to the portal. This is permanent and cannot be undone.

 

If you would like to deactivate a user instead, refer to PATCH Users {username} in the API Reference section.

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

The following screenshot shows a sample curl request for this method.

curl -X
POST "https://api.equinix.com/access/v2/users/accessChange"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "id": "johndoe1",
  "idType": "USERNAME"
  "action": "TERMINATE",
  "reason": "User is no longer in the organization."
}'

The description of the body parameters is as follows:

Body Parameter name	Mandatory	Type	Example	Applicable Values	Description
id	Yes	string	johndoe1		ID of the user. This ID is defined by the parameter 'idType'.
idType	No	string	USERNAME	USERNAME	Type of ID. Default value: USERNAME
action	Yes	string	TERMINATE	TERMINATE	Action to change the user's access to the portal.
reason	Yes	string	User is no longer in the organization.		Reason for terminating the user's access to the portal. Limit: 1 to 250 characters.

User is successfully terminated when an HTTP code of 202 and the following response header is returned. There is no response body.

HTTP Response Header Name	Description
Location	Location of the user. Example: /users/{username}   To verify the user's portal access has been terminated, refer to GET Users {username}.

 

If you get “Insufficient permissions” error, contact your Master Administrator.