Access and Authentication

Pre-requisites

• You have valid user credentials to access Equinix Developer Portal.
• You have subscribed to Equinix Messaging Gateway.
• You have configured Equinix Queue connection details in your system.
• You have authorized permissions for orders and notifications by your Master Administrator.

---

Authentication Method

 

Deprecation of Client Credentials (Client ID and Client Secret)

Switching from Client Credentials to Access Tokens - Starting March 18, 2024, EMG requires access tokens instead of client IDs and client secrets as an authentication method. Both methods will be supported until September 17, 2025, giving you time to transition. After that date, only access tokens will be accepted.

You can switch to access tokens with the AccessToken_v1 API. Check also our guide Getting Access Token.

The deprecation does not affect your integration if you use certificate-based authentication or receive outbound notifications through the EMG.

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

You can choose the preferred authentication method for your application while subscribing to the EMG. The following authentication methods are available:

• Client Credentials (Client ID and Client Secret) DEPRECATED
• Access Token
• Certificate-based Authentication

---

Client Credentials

DEPRECATED

More

Authentication using the Client Credentials method allows you to:

• Create a new application or
• Select an existing application

 

For a new application
Provide the application name and obtain the Credential Details: Client ID and Client Secret. Both ClientId and ClientSecret values are part of the Authentication section in the EMG message.

"Authentication": {
    "ClientId": "e7J**********P3Y",
    "ClientSecret": "usO**********mWv"
    }

---

Access Token

More

Initiate the process of Getting Access Token.

 

Important Update on the Access Token API:

Access Token: As of January 8, 2024, we deprecated the use of 'password grant type' for generating new access tokens. The end-of-life support will end on January 7, 2025, and API calls will be retired and removed after this date. If you currently use the password grant type, we highly recommend migrating to client credential flow to avoid impacting your integration.

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

Equinix APIs use OAuth 2.0 protocol to authenticate the requests you make to API endpoints. In order to interact with Equinix APIs, you need a bearer access token. Bearer determines the type of authentication scheme and is a part of the OAuth 2.0 protocol.

Prerequisites

Interacting with Equinix products over API requires:

• Equinix portal account.
• Product-specific create, modify and delete permissions. Contact your organization's primary administrator and request access permissions.

 

Generate Client ID and Client Secret

Client ID and Client Secret are necessary to obtain tokens that authorize your API requests. To generate a Client ID (Consumer Key) and Client Secret (Consumer Secret), register your app in the Developer Settings section of the Equinix Portal.

To register app:

1. Log in to Equinix Portal.

2. From the global navigation menu, select Developer Settings > Apps to display apps details.

 

API License Agreement
Before using the platform and APIs for the first time, you must read and accept the displayed API license agreement. Once you have accepted the agreement, you can find it in the Additional Information section.

Details: API License Agreement and Additional Information

3. Click Create New App.
   

4. Provide app name, select app environment type (Sandbox or Production), and click Create.
   

 

Sandbox simulates the production environment. You can use it to test your API integration if you're an API-enabled customer.

The Sandbox environment is not supported for Fabric customers.

5. Click your app tile to open its details.

6. Click Show (eye icon) to view your Consumer Key and Consumer Secret.
   

 

Request Access and Refresh Tokens

Access Token

Access token is used to authorize your API requests. You can request a token using either client credentials (recommended) or password grant type DEPRECATED.

 

For more information on grant types, see OAuth Grant Types.

Sample curl request - client credentials grant type (recommended)

curl -X
POST 'https://api.equinix.com/oauth2/v1/token'
-H 'content-type: application/json'
-d '{
    "grant_type": "client_credentials",
    "client_id": "ABCDE12345",
    "client_secret": "FGHIJ67890"
}'

DEPRECATED

Sample curl request - password grant type

curl -X
POST 'https://api.equinix.com/oauth2/v1/token'
-H 'content-type: application/json'
-d '{
    "grant_type": "password",
    "client_id": "ABCDE12345",
    "client_secret": "FGHIJ67890",
    "user_name": "john.doe@example.com",
    "user_password": "jd1@#$"
}'

DEPRECATED

 

For increased security, you can provide an MD5 hash of your password encoded using Base64 encoding.

Sample curl request - password grant type with hashed password string

curl -X
POST 'https://api.equinix.com/oauth2/v1/token'
-H 'content-type: application/json'
-d '{
    "grant_type": "password",
    "client_id": "ABCDE12345",
    "client_secret": "FGHIJ67890",
    "user_name": "john.doe@example.com",
    "user_password": "pJThQGD0QG7R0iedSipwIA==",
    "password_encoding": "md5-b64"
}'

Example python script for generating password hash:

import hashlib
import base64

a = hashlib.md5('jd1@#$'.encode('utf8'))
b = base64.b64encode(a.digest()).decode()
print(b)

Body parameters

Parameter	Description
grant_type string REQUIRED	Different ways to authorize access to resources. Applicable values: client_credentials password DEPRECATED
client_id string REQUIRED	Client application identifier. For information on how to generate and retrieve client application identifier, see Generate Client ID and Client Secret. Example: ABCDE12345
client_secret string REQUIRED	Authorization key associated with an application instance. For information on how to generate and retrieve client application secret, see Generate Client ID and Client Secret. Example: FGHIJ67890
user_name string CONDITIONAL	Your Equinix account username. Applicable to the password grant type DEPRECATED. Example: john.doe@example.com
user_password string CONDITIONAL	Your Equinix account password. Applicable to the password grant type. DEPRECATED Example: jd1@#$
password_encoding string OPTIONAL	A hashing algorithm and encoding applied to the password string. Applicable to the password grant type. DEPRECATED Applicable values: md5-b64

Sample response - client credentials grant type

{
    "access_token": "qwErtY8zyW1abcdefGHI",
    "token_timeout": "3600",
    "user_name": "john.doe@example.com",
    "token_type": "Bearer"
}

DEPRECATED

Sample response - password grant type

{
    "access_token": "qwErtY8zyW1abcdefGHI",
    "token_timeout": "3600",
    "user_name": "john.doe@example.com",
    "token_type": "Bearer",
    "refresh_token": "zxcvbn1JKLMNOPQRSTU",
    "refresh_token_timeout": "5184000"
}

Response payload body description

Parameter	Description
access_token string	API requests authorization token. Example: qwErtY8zyW1abcdefGHI
token_timeout string	Authorization token lifetime expressed in seconds. Example: 3600
user_name string	Equinix account username. Example: john.doe@example.com
token_type string	Authorization token type. Example: Bearer
refresh_token string	Refresh token used to obtain a new access token once it expires. Example: zxcvbn1JKLMNOPQRSTU
refresh_token_timeout string	Refresh token lifetime expressed in seconds. Applicable values: 5184000

Refresh Token

Use a refresh token to obtain a new access token.

Sample curl request - retrieve access token using a refresh token

curl -X
POST 'https://api.equinix.com/oauth2/v1/refreshaccesstoken'
-H 'content-type: application/json'
-d '{
    "client_id": "ABCDE12345",
    "client_secret": "FGHIJ67890",
    "refresh_token": "zxcvbn1JKLMNOPQRSTU"
}'‌‌

Body parameters

Parameter	Description
client_id string REQUIRED	Client application identifier. For information on how to generate and retrieve client application identifier, see Generate Client ID and Client Secret. Example: ABCDE12345
client_secret string REQUIRED	Authorization key associated with an application instance. For information on how to generate and retrieve client application secret, see Generate Client ID and Client Secret. Example: FGHIJ67890
refresh_token string REQUIRED	Refresh token used to obtain a new access token once it expires. Example: zxcvbn1JKLMNOPQRSTU

 

Use Access Tokens

To interact with Equinix API, make sure to include the Authorization header in the HTTP request.

Sample curl request - an inbound shipment

curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "type": "INBOUND",
  "requestedDateTime": "2020-11-02T10:45:41Z",
  "cageId": "AM1:01:000111",
  "details": {
    "carrier": "CUSTOMER_CARRIER",
    "numberOfBoxes": 2
  }
}'

Sample Request:

{
  "Task": {
    "Id": "bf9f2707-d612-4d63-9958-4c8b1fcf3cc0",
    "Source": "3e095d30-40ff-11e9-8959-5be078353003",
    "Verb": "Create",
    "Resource": "SmartHands",
    "ContentType": "application/json",
    "Version": "1.0",
    "Body": {
      "RequestorId": "123456789",
      "RequestorIdUnique": true,
      "Operation": "0001",
      "Description": "Create SmartHands Order",
      "Attachments": [
        {
          "Name": "samplepicture.jpeg",
          "Url": "https://eqixazurestorage.blob.core.windows.net/file-download-blob/samplepicture.jpeg"          
        }
      ],       
      "Location": "LD8:00:000000",
      "CustomerContact": "demo@equinix.com",
      "SchedulingDetails": {
        "RequestedStartDate": null,
        "RequestedCompletionDate": null
      }
    }
  },
  "Authentication": {
    "AccessToken": "<AccessToken>"
  }
}

---

Certificate (RSA-SHA256)

Equinix supports certificate-based authentication as a part of the EMG subscription.

This method requests the primary and secondary public keys to authenticate your data.

The certificate is signed using a secure hashing algorithm (SHA256) with an RSA signature to help you encrypt and decrypt information. You create a public-private key pair and then share the public key with Equinix. The public key is used for encryption, and the private key is used for decryption.

Generate Signature

To generate a signature using RSA-SHA256 encryption, you need the EMG message and your private key. Pass the encrypted value in the Signature field in the EMG message after successful generation.

Sample Request:

{
  "Task": {
    "Id": "bf9f2707-d612-4d63-9958-4c8b1fcf3cc0",
    "Source": "3e095d30-40ff-11e9-8959-5be078353003",
    "Verb": "Create",
    "Resource": "SmartHands",
    "ContentType": "application/json",
    "Version": "1.0",
    "Body": {
      "RequestorId": "123456789",
      "RequestorIdUnique": true,
      "Operation": "0001",
      "Description": "Create SmartHands Order",
      "Attachments": [
        {
          "Name": "samplepicture.jpeg",
          "Url": "https://eqixazurestorage.blob.core.windows.net/file-download-blob/samplepicture.jpeg"          
        }
      ],       
      "Location": "LD8:00:000000",
      "CustomerContact": "demo@equinix.com",
      "SchedulingDetails": {
        "RequestedStartDate": null,
        "RequestedCompletionDate": null
      }
    }
  },
  "Signature": "RWNobwp7CiAgIklkIjogIjM1MGFlZjcwLTc4MWItMTFlOSogIH0KfQ=="
}

How to generate a signature (Mandatory)

1. Create an RSA-SHA256 signature.
2. Stringify the Task object.
3. Update the signature using the stringified task object.
4. Compute the signature using your private key and encode using base64 encoding.

How to verify the signature (Optional)

1. Create a verifier using the RSA-SHA256 signature scheme.
2. Update the verifier with the Task string in the incoming message.
3. Verify using Equinix public key and base64 encoded signature from the incoming message.