Skip to main content

API Authentication

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.

info

The Equinix Metal API does not use the authentication flow described here. Metal API keys are managed through the Metal console, and its authentication is documented in the API Reference.

Prerequisites​

Interacting with Equinix products over API requires:

  • An Equinix Customer 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​

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

To register an app:

  1. Sign in to the Customer Portal.

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

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

  4. Click Create New App.

  5. Provide an 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.

  6. Click your app tile to open its details.

  7. Click the eye icon to view your Consumer Key and Consumer Secret.

Requesting an Access Token​

An access token is required to authorize your API requests. To request a token, send a POST request to the /oauth2/v1/token endpoint, specifying your Client ID and Client Secret in the body of the request.

Sample cURL request:

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

For a complete list of available parameters and options, see the API Reference.

Sample response:

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

Refreshing a Token​

You can refresh your access token by sending a POST request to the /oauth2/v1/refreshaccesstoken endpoint.

Sample curl request:

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

For a complete list of available parameters and options, see the API Reference

Using Access Tokens​

To interact with Equinix API, send your access token in the Authorization header of the HTTP request with authorization: Bearer <token>

Sample cURL request - an inbound shipment from the colocation API:

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