Skip to main content
Index

Users (V2)

Users (V2) API allows an authenticated user with the required permissions to create, retrieve, update or terminate users within their organizations.

 

To create or terminate a user, refer to User Management under the the How to Guide section. All other methods can be found below.

GET Users

GET /users

 Method  GET
 URL or End Point  /access/v2/users
 Headers  Authorization, Content-Type
 Query Parameters  keyword, status, favoriteOnly, userRoles, sorts, offset, limit
 Body  Not applicable

 

This method retrieves a list of existing portal users in your organization based on your search criteria. Only an authenticated user from your organization with portal access can use this method.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 Started section.

 

The following screenshots show a sample curl request and JSON response for this method. The request was for a user retrieving their own profile information, and the response returned shows the request was successful.

 

curl -X

GET "https://api.equinix.com/access/v2/users?keyword=John&status=ACTIVE,APPROVED,LOCKED&favoriteOnly=true&userRoles=USER&sorts=STATUS&offset=0&limit=1"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameter is as follows:

 

Query Parameter name Mandatory Type Example

Applicable Values

Description
keyword No string John  

Filters search according to this keyword. This is free text input. 

 

For example, this could be a first name (given name), last name (surname), username, or primary email. Any user with this keyword in their first name, last name, username or primary email address will be returned.

 

Limit: 1200 characters

status No

array

[strings]

ACTIVE,

APPROVED,

LOCKED

NEW,
APPROVED,
ACTIVE,
INACTIVE,

LOCKED,

TERMINATED

Status of the user. Multiple statuses should be comma-separated.

 

Default value: all statuses except TERMINATED

 

Status - Description

NEW - User was invited by the administrator through the portal, and submitted their user profile for your administrator approval. 

APPROVED - User was created or approved by your administrator. User can be listed as a notification or technical contact.
ACTIVE - Approved user with permissions assigned by your administrator. Once a user has their password created, they can log into the portal. User can be an ordering, notification or technical contact.

INACTIVE - User was deactivated, and can no longer access the portal or IBX. 

LOCKED - User profile is locked. User is unable to log into the portal, but can still be listed as a notification or technical contact.

TERMINATED - User's portal profile, permissions, and IBX access have been terminated. This status is permanent and cannot be changed. 

favoriteOnly No boolean true

true,

false

Searches for users marked as favorite.

 

Default value: false

 

When true, only favorite users of the authenticated user will be returned. When false, all users will be returned. 

userRoles No

array

[strings]

USER

MASTER_ADMINISTRATOR,

IBX_ADMINISTRATOR,

USER

User role or portal user type. Multiple roles should be comma-separated.

 

Default value: all user roles

 

User role - Description

MASTER_ADMINISTRATOR - Master Administrators can create and manage other master administrators, IBX administrators and common users for all IBXs. 

IBX_ADMINISTRATOR - IBX Administrators may create and manage common users for selected IBXs or cages.

USER - Common user with permissions assigned to them by Master or IBX administrators.

sorts No

array

[string]

STATUS

EMAIL,

FIRST_NAME,

LAST_NAME,

ROLE,

STATUS,

-EMAIL,

-FIRST_NAME,

-LAST_NAME,

-ROLE,

-STATUS

Sorting preference for the returned record.

 

Default: Users are sorted in descending order of their activation date

 

Sorts - Description

EMAIL - Users will be returned in ascending alphanumeric order of their primary email address.

FIRST_NAME - Users will be returned in ascending alphanumeric order of their first or given name.

LAST_NAME - Users will be returned in ascending alphanumeric order of their last name or surname.

ROLE - Users will be returned in ascending alphanumeric order of their user role.

STATUS - Users will be returned in ascending alphanumeric order of their user status.

 

When these sorts values are prefixed by '-' users will be returned in descending order instead.

offset No integer 0  

Defines the index of the first record returned in the response. By specifying the offset, the response returns a subset of records starting with the offset value.

 

For example, if the offset is 10, the starting record returned in the response would be the 11th record. 

 

Default value: 0

limit No integer 1  

Defines the maximum number of records returned in your query. 

 

Default value: 10

 

Limit: 1 to 200

 

{
  "data": [
    {
      "username": "johndoe1",
      "firstName": "John",
      "lastName": "Doe",
      "email": "johndoe@corp.com",
      "status": "ACTIVE",
      "securityProfile": "COMPLETED",
      "userRole": "USER",
      "isFavourite": true
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 1,
    "total": 1,
    "next": "/users?keyword=John&status=ACTIVE,APPROVED,LOCKED&favoriteOnly=true&userRoles=USER&sorts=STATUS&offset=0&limit=1",
    "previous": "/users?keyword=John&status=ACTIVE,APPROVED,LOCKED&favoriteOnly=true&userRoles=USER&sorts=STATUS&offset=0&limit=1"
  }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
data

array

[objects]

  Data returned from your query. Each user object comprises the following fields where applicable: username, firstName, lastName, email, status, securityProfile, userRole, isFavourite.
username string johndoe1 Username of the portal user.
firstName string Johnathan Legal first name or given name.
lastName string

Doe

Legal last name, surname, or family name.
email string johndoe@corp.com Primary email address.
status string ACTIVE

Status of the user.

 

Refer to the description of query parameter 'status' for more information.

securityProfile string COMPLETED

IBX security profile status.

 

Security profile status - Description

COMPLETED - User has set up their security profile to access the IBX.

NOT_COMPLETED - User has not completed setting up their security profile. Until their security profile is completed, they cannot physically access any IBX.

userRole string USER

User role or portal user type. 

 

Refer to the description of query parameter 'userRole' for more information.

isFavourite boolean true

Favorite status of the user.

 

Refer to the description of query parameter 'FavouriteOnly' for more information.

pagination object   Page information. This object comprises the following fields: offset, limit, total, next, previous.
offset integer 1

Offset of the first record in the response, as defined in the query parameter 'offset'.

limit integer 1

Maximum number of records in the response, as defined in the query parameter 'limit'.

total integer 11

Total number of available records.

next string /users?offset=1&limit=1 URL for the next page of results.
previous string  /users?offset=0&limit=1 URL for the previous page of results.

 

To verify the username is associated with the intended user, retrieve the user's profile for further details with GET Users {username}. This method is applicable for existing portal users, and does not apply to terminated users. 

 

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

GET Users {username}

GET /users/{username}

 Method  GET
 URL or End Point  /access/v2/users/{username}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

This method retrieves a portal user's profile details by their username. An authenticated user with any portal permissions may retrieve the profile information of any user in their organization. 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.

 

This method retrieves the user profiles for users with the following statuses:

  • NEW
  • APPROVED
  • ACTIVE
  • LOCKED
  • INACTIVE

For more information on these statuses, refer below to the description of the response payload field 'status'. 

 

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

 

The following screenshots show a sample curl request and JSON response for this method. The request was for a user retrieving their own profile information, and the response returned shows the request was successful.

 

curl -X

GET "https://api.equinix.com/access/v2/users/johndoe1"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the URL parameters is as follows:

 

URL Parameter name Mandatory Type Example

Applicable Values

Description
username Yes string johndoe1  

Username of the portal user whose profile you wish to retrieve.

 

If you are unsure of the exact username, contact your Master Administrator. 

Limit: 8-250 characters.

 

{
  "status": "ACTIVE",
  "username": "johndoe1",
  "firstName": "John",
  "lastName": "Doe",
  "localName": "ジョン・ドー",
  "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"
    }
  ],
  "companyName": "Sample Company",
  "companyLocalName": "サンプル会社",
  "title": "Manager",
  "department": "Procurement",
  "deactivationDateTime": "2022-01-29T01:10:11Z",
  "timezone": "Asia/Tokyo",
  "locale": "JA_JP"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
status string ACTIVE

Status of the user.

 

Status - Description

NEW - User was invited by the administrator through the portal, and submitted their user profile for your administrator approval. 

APPROVED - User was created or approved by your administrator. User can be listed as a notification or technical contact.
ACTIVE - Approved user with permissions assigned by your administrator. Once a user has their password created, they can log into the portal. User can be an ordering, notification or technical contact.

INACTIVE - User was deactivated, and can no longer access the portal. 

LOCKED - User profile is locked. User is unable to log into the portal, but can still be listed as a notification or technical contact.


Profiles of users with other statuses will not be returned. 

username string johndoe1 Username of the portal user. This is either provided during the user profile creation, or defaulted to the user's primary email address when the username was not provided.
firstName string Johnathan Legal first name or given name. 
lastName string

Doe

Legal last name, surname, or family name.
localName string ジョン・ドー

User's legal name in non-Western characters.

contactDetails array 
[objects]
 

List of contact details for this person. Each contact detail object consists of the following fields: type, value. 

type string PHONE

Type of contact detail in the type-value pair. 

 

Type - Description

PHONE - Primary phone number. 

EMAIL - Email address.

MOBILE - Mobile phone number. This is the secondary contact number.
SECONDARY_EMAIL - Secondary email address.

value string +1-987-654-3210 Value related to the contact detail type in the type-value pair.
companyName string Sample Company Company name associated with user. 
companyLocalName string サンプル会社 Name of the company in non-Western characters.
title string Manager Job title or designation of user.
department string Procurement Department to which the new user belongs.
deactivationDateTime string 2022-01-29T01:10:11Z Future date and time that user would be deactivated.
timezone string Asia/Tokyo

User's preferred time zone to be contacted. 

 

For a full list of time zones, see Time Zone in the Appendix.

locale string EN_US Preferred language of the user.

For a full list of locale codes, see Locale Codes in the Appendix.

 

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

PATCH Users {username}

PATCH /users/{username}

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

 

This method updates a user's profile details. An authenticated user with portal permissions can update their own profile, while an authenticated user with administrator privileges can update other users profiles. 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 Started section.

 

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

 

(A) A user updating their own profile. All applicable body parameters are passed in this sample request. 

 

(B) An administrator updating another user's profile. All applicable body parameters are passed in this sample request.

 

(C) An administrator deactivating another user. Only the minimum required body parameters are passed in this sample request payload. 

 

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

 

(A) User updating their own profile

In this scenario, a user is updating all the information in their profile. All applicable body parameters for this scenario are passed in this sample request. 

 

curl -X

GET "https://api.equinix.com/v1/users/johndoe1"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "firstName": "John",
  "lastName": "Doe",
  "localName": "ジョン・ドー",
  "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"
    }
  ],
  "companyName": "Sample Company",
  "companyLocalName": "サンプル会社",
  "title": "Manager",
  "department": "Procurement",
  "timezone": "Asia/Tokyo",
  "locale": "JA_JP"
}

 

(B) Administrator updating another user's profile

The administrator is updating all the information in the user's profile, including the user's deactivation date. Deactivating a user can only be done by an administrator. All available and applicable body parameters are passed in this sample request.

 

curl -X

GET "https://api.equinix.com/v1/users/johndoe1"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "firstName": "John",
  "lastName": "Doe",
  "localName": "ジョン・ドー",
  "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"
    }
  ],
  "companyName": "Sample Company",
  "companyLocalName": "サンプル会社",
  "title": "Manager",
  "department": "Procurement",
  "timezone": "Asia/Tokyo",
  "locale": "JA_JP",

  "deactivationDateTime": "2022-01-29T01:10:11Z"
}

 

(C) Administrator deactivating another user

In this scenario, the administrator is deactivating a user. The minimum required information for this scenario is passed in this sample request.

 

curl -X

GET "https://api.equinix.com/v1/users/johndoe1"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "deactivationDateTime": "2022-01-29T01:10:11Z"
}

 

The description of the URL parameters is as follows:

 

URL Parameter name Mandatory Type Example

Applicable Values

Description
username Yes string johndoe1  

The username of the user whose profile you wish to retrieve.

 

To get the username, contact your Master Administrator. 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
firstName No string Johnathan  

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 No 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.

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.

contactDetails No array 
[objects]
   

Contact details for this person. Each contact detail object consists of the following fields: type, value. 

type Conditional string PHONE  

Type of contact detail in the type-value pair. 

 

Type - Description

PHONE - Primary phone number. 

EMAIL - Email address.

MOBILE - Mobile phone number. This is the secondary contact number.
SECONDARY_EMAIL - Secondary email address.

value Conditional string +1-987-654-3210   Value related to the contact detail type in the type-value pair.
companyName No string Sample Company  

Company name associated with user. 

 

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 user.
department No string Procurement   Department to which the new user belongs.
timezone No string Asia/Tokyo Click here for applicable values. 

User's time zone to be contacted. 

locale No string EN_US Click here for applicable values.  User's preferred language in the Equinix portal.
deactivationDateTime No string 2022-01-29T01:10:11Z   Date and time the user should be deactivated.
 

This field can only be updated by an authenticated user with administrator privileges. 

 

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