https://developer.equinix.com
For Public Viewing
body: 

Legend        Don't like reading - How about a 1-minute video?       Ask us

 

What is Network Edge?

Network Edge (NE) is a platform that allows customers to deploy and run virtual network services and appliances such as routers, load balancers, and firewalls on a generic device instead of additional dedicated hardware, CapEx and colo space.

 

Network Edge offers the following capabilities:

  • Edge device lifecycle management - High availability (HA) and non-HA device management for routers, firewall, SD-WAN and many more.
  • Cloud to cloud routing - Connectivity to multiple cloud service providers.
  • SSH user management for virtual devices
  • BGP peering - A single stop for A-side and Z-side peering.
  • VPN configuration

 

Network Edge is offered to customers through Network Edge portal and REST APIs.

 

 

body: 

What are Network Edge APIs?

Network Edge APIs are a collection of REST APIs that allows you to interact with Equinix programmatically to create a virtual device and add services. The following Network Edge APIs are currently available to customers (Refer API reference section for more details.)

 


body: 

How do the Network Edge APIs work?

Background

When a customer is onboarded, they are provided with user credentials. 

 

 

The customer must use these credentials to connect to the Equinix Developer Platform to generate a Consumer key and Consumer secret. 

 

 

The Consumer key and Consumer secret are essential for obtaining access and refresh tokens to authenticate API calls as described in the subsequent section.

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to generate Consumer key and Consumer secret.

 

Network Edge Workflow

 

 

Step 1  - Obtain a perpetual license from the device manufacturer. Alternatively, you can request for a subscription license from Equinix.

 

Refer to <URL> for details on the different subscriptions offered by Equinix.

 

Authorization flow:

Step 2  - Request access and refresh token information by calling the Equinix OAuth API (/oauth2/v1/token) with the Consumer key, Consumer secret, and user credentials. 

 

 

Refer to Requesting Access and Refresh tokens under the Getting Started for instructions on how to obtain an Authorization Token.

 

Step 3  - The API gateway makes an OAuth2 call to the identity provider using the submitted credentials.

 

Step 4  - The identity provider returns an OAuth2Access token to the API gateway.

 

Step 5  - The API gateway sends back the authorization token details to the client.

 

API Request flow:

Step 6  - The customer submits an API request with the obtained authorization token and respective API request payload.

 

 

Refer to the How-to Guide section for instructions on how to call Network Edge APIs to create devices, establish connections, setup VPN and many more

 

Step 7  - API gateway validates the request and calls the relevant APIs to create devices and cloud connections.

 

Step 8  - The response is received by the API gateway.

 

Step 9  - The response is sent back to the customer.

 


body: 

How-to Guide for Network Edge use cases

Learn how to build solutions using Network Edge APIs!

 

  • Virtual device lifecycle management

Launch virtual devices          

 

Connect to AWS          

Connect to Azure          

Connect to Google          

Connect to Oracle

 

 

  • User to cloud via SD-WAN

Create and launch SD-WAN          

 

  • Branch to cloud via VPN 

Establish VPN connectivity         

 

  • Firewall

 


body: 

Pre-requisites

•   You have valid user credentials.
•   You have been authorized to access the developer portal.
•   You have been authorized to create, modify and delete connections by your master Admin.

 


body: 

Getting Started

Learn the fundamentals of Equinix APIs.

 


body: 

Generating Client ID and Client Secret key

To obtain your client ID (consumer key) and client secret key (consumer secret), you must register your app in the developer portal according to your preferred environment. 

1. Login to Equinix Developer Platform using your login credentials.

 

If you are unaware of your login credentials for Equinix Developer Platform, contact your local Equinix Service Desk.

 

2. After logging in, click on the My Apps section as shown below.

 

 

3. Click on the Create New App button.

 

 

4. You will need to name your app and then select the app type to be used, you can either create an app for the Sandbox or Production environment. Once you’re ready click on the Create App button.

 

The sandbox environment is only a test environment that mimics the production environment and creates simulated API responses. 

If you are not an existing API customer, send an email to api-support@equnix.com to gain access to Equinix sandbox.

 

 

5. You should now have your app listed in the My Apps section as shown below:

 

 

6. When you select the application, your Client ID ( Consumer Key) and Client Secret (Consumer Secret) will be revealed.

 

 


body: 

Requesting Access and Refresh tokens

Access Token Flow

The access token is used to exchange data with the Equinix APIs and the refresh token is used to request a new access token should the access token expire. You can obtain your access token by either using the password or client credentials grant type as shown in the sample curl commands below:

 

The client_credentials grant type is used by users who do not want to use their Equinix login credentials (user name and user password) in exchange for an access token, whereas the password grant type is for users who are less hesitant. 

 

Refer to https://oauth.net/2/grant-types/ for more information about the different grant types and their usage. 

 

Access token using password grant type

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/token'

-H "content-type: application/json" 

-d '{

"grant_type": "password",

"user_name": "john.doe@example.com",

"user_password": "jd1@#$",

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890"

}'

 

Access token using client credentials grant type

 

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"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
grant_type Yes string password

"password"

"client_credentials"

Different ways to authorize access to resources. It indicates the type of grant to be presented in exchange for an access token.
user_name Yes string john.doe@example.com   The Equinix login username. This field is optional for client credentials grant type.
user_password Yes string jd1@#$   The Equinix login password. This field is optional for client credentials grant type.
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Portal.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer portal.
password_encoding No string md5-b64 "md5-b64"

An optional field for users who wish to encrypt their password when requesting an access token. Currently, only “md5-b64” hashing is supported. This field is only applicable to users who use password grant. 

 

 

Click here to learn how to encrypt your password using md5-b64 hashing.

 

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to create a client ID and client secret.

 

If you are unaware of your user credentials for the Equinix Developer Platform, contact your local Equinix Service Desk. 

 

Once authenticated, the respective token and timeout details will be sent to you as shown in the sample JSON responses below.

 

Sample response when using 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"

}

 

Refresh token details will only be sent to customers that use password grant.

 

Sample response when using client credentials grant type

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

}

 

The description of the response payload is as follows:

 

Field Name Type Example Applicable Values Description
access_token string qwErtY8zyW1abcdefGHI   The authorization token to be used in subsequent API calls. 
token_timeout string 3600   The lifetime of an access token in seconds. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
user_name string john.doe@example.com   The Equinix login username.
token_type string Bearer

"Bearer"

The type of token. 
refresh_token string zxcvbn1JKLMNOPQRSTU   Access tokens have limited lifetimes. If your application needs access to an API beyond the lifetime of a single access token, you can obtain a refresh token. A refresh token allows your application to obtain new access tokens. This information is only applicable to "password" grant users. 
refresh_token_timeout string 5184000   The lifetime of a refresh token in seconds. For example, the value "5184000" denotes that the refresh token will expire in 60 days from the time the response was generated. This information is only applicable to "password" grant users.

 

To make a request to Equinix APIs, add the Authorization header to the HTTP request with the word "Bearer" prepended to the access token. For example with curl use,  -H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Refresh Token Flow

You can use a valid refresh token to obtain new access tokens to be used in API calls. A refresh token is valid for 60 days. You must submit your Client ID, Client Secret and Refresh Token to obtain refresh access tokens as shown in the sample curl command below.

 

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"

}'

 

The description of the body parameters are as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Portal.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer portal.
refresh_token Yes string zxcvbn1JKLMNOPQRSTU   A refresh token allows your application to obtain a new access token and is provided in the response payload of an access token call.

 

Once requested, a new set of access token, refresh token, and timeout details will be sent to you.

 

{

    "access_token": "1abcdefGHIqwErtY8zyW",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

    "refresh_token": "1JKLMNOPQRSTUzxcvbn",

    "refresh_token_timeout": "5184000"

}

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to create a client ID and client secret.

 


body: 

Launch virtual devices

 

 

To create a virtual device you must know the following:

 

1) Which virtual device type (deviceTypeCode) you want, what software type (packageCode) you need, and the location where you want your virtual device (metroCode).

2) Equinix account number. Your account must be in the Active or Pending status. 

3) License option (licenseMode). If you want a subscription license (Equinix manages license and charges monthly), then you do not need to worry about licensing options. 

 

If you have all the necessary information, then skip ahead to Step 4 and create a virtual device. Otherwise, follow the steps to get information and create a device:

 

If you do not have all the necessary information, you can still save as a draft. You must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode to save a draft.

 

Refer to the Network Edge deployment guide to know pre-requisites/conditions to bring your own license option (BYOL) and for other additional services like BGP peering, and VPN configuration.

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Network Edge, contact your local Equinix Service Desk. 

 


body: 
Step 2: Get metro, device types, and account

 

2a) Get metro

 

Call Get metro API to find out all the available metros (metroCode) where you can launch a virtual device.  

 

You may skip this step if you already know the available metros.

 

 

2b) Get device types

 

Call Get device types API to find out which virtual device (e.g., router or firewall) you want to launch on the NE platform (deviceTypeCode). You will learn about the metro regions where virtual devices are available (metroCode), vendors of devices, available software packages (packageCode), and all possible licensing and throughput options.  

 

You may skip this step if you already know which device you want.

 

2c) Get account

 

Call Get account API to check your account number (or acountReferenceId) and status in the metro where you want a virtual device. For billing reasons, you must have an account in the metro where you want a virtual device, either in the Active or Pending state. To create an account go to accountcreateurl.

 

You may skip this step if you already know your account number (or accountReferenceId) and status.  

 


body: 
Step 3: Licensing options 

If you want to BYOL (bring your own license) then you may want to upload a license file or a license code/token/ID depending on what your vendor offers.

 

   For Cisco devices, you can upload a license file after you create a virtual device.

   For Juniper devices, you need to upload the license file before you create a device.

   For Palo Alto devices, a license token is necessary to create a device. 

 

There are three APIs to address each of the licensing scenarios in case you want to bring your own license (BYOL). Check the Network Edge deployment guide for licensing options for all the available virtual devices. 

 

3a) Post a license file before creating a device

To bring your own license (BYOL) for a Juniper device, use Post a license file before creating a device API. You will get a file ID that you can use to create a virtual device. In case you have an HA Juniper device that has a secondary device for high availability, you can use the same fileId for both the primary and secondary devices. 

 

You may skip this step if you don't want to post a license before creating a device or if you want subscription licensing.

 

3b) Post a license file after creating a device

If you want to bring your own license (BYOL) and have already created a virtual device, use Post a license file after creating a device  API to post a license file. You can also use this API to renew a license that is about to expire. This API is useful for Cisco devices where you can upload a license file after creating a device. You must upload two files in case you have a Cisco HA device that has a secondary device for high availability. 

 

You may skip this step if you've already posted a license or if you want subscription licensing.

 

3c) Post a license code/token/ID

If you have a Palo Alto device, you can use Post a license code/token/ID  API to update a license token/code/ID that is about to expire. You may use the same or two different tokens in case you have a Palo Alto HA device that has a secondary device for high availability. 

 

You may skip this step if you've already posted a token or if you want subscription licensing.

 


body: 
Step 4: Create virtual devices

POST /ne/v1/device

 Method  POST
 URL or End Point  /ne/v1/device
 Headers  Authorization token, Content-Type
 Query Parameters  draft, draftUUID
 Body Parameters

 additionalBandwidth, deviceTypeCode, hostNamePrefix, licenseFileId, licenseMode, licenseToken, metroCode, 

 notifications[...], packageCode, termLength,

 throughput, throughputUnit, virtualDeviceName,   acl[...], accountNumber, accountReferenceId, 

 purchaseOrderNumber, secondary   {accountNumber, accountReferenceId, additionalBandwidth, licenseFileId, 

 licenseToken, metroCode, notifications[...], acl[...],

 sshUsers[{sshUserUuid, action, sshUsername, sshPassword}], virtualDeviceName"}

 

To create an HA device that has a secondary device for high availability, please do the following:

 

1) Set parameters of the optional secondary object

 

2) Both devices use the same license type, either SUB (subscription) or BYOL (bring your own license). In case you want to BYOL for an HA device, you may or may not need two different license files or tokens depending on your choice of vendor.

 

   a) For Cisco HA device, you will need two different license files if you want to BYOL (bring your own license). 

   b) For Juniper HA device, you may or may not use the same license file if you want to BYOL (bring your own license). 

   c) For Palo Alto HA device, you may or may not use the same license tokens in case you want to BYOL (bring your own license).

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request to create a virtual device with NO secondary device (non-HA).

 

curl -X

POST "https://api.equinix.com/ne/v1/device?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{

  "throughput":500,

  "throughputUnit":"Mbps",

  "metroCode":"DC",

  "deviceTypeCode":"CSR1000V",

  "termLength":"12",

  "licenseMode":"Sub",

  "packageCode":"SEC",

  "virtualDeviceName":"Test-device-006-SROY",

  "notifications":["mest@equinix.com","test@equinix.com"],

  "hostNamePrefix":"SROY123",

  "sshUsers":[{"action":"CREATE","sshUsername":"tatiyana1","sshPassword":"Tatiyana"},{"action":"REUSE","sshUserUuid":"72902689-dff7-437d-8832-4bc8f3495252"}],

  "acl":["10.10.10.1/32"],

  "purchaseOrderNumber":"234567",

  "accountNumber":"2252619",

  "additionalBandwidth":"100"

}'

 

The following screenshot shows a sample curl request to create an HA virtual device that has a secondary device for high availability (HA). 

 

curl -X

POST "https://api.equinix.com/ne/v1/device?draft=false"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{

  "throughput":500,

  "throughputUnit":"Mbps",

  "metroCode":"DC",

  "deviceTypeCode":"CSR1000V",

  "termLength":"12",

  "licenseMode":"Sub",

  "packageCode":"SEC",

  "virtualDeviceName":"Test-device-006-SROY",

  "notifications":["mest@equinix.com","test@equinix.com"],

  "hostNamePrefix":"SROY123",

  "sshUsers":[{"action":"CREATE","sshUsername":"tatiyana1","sshPassword":"Tatiyana"},{"action":"REUSE","sshUserUuid":"72902689-dff7-437d-8832-4bc8f3495252"}],

  "acl":["10.10.10.1/32"],

  "purchaseOrderNumber":"234567",

  "accountNumber":"2252619",

  "secondary":

  {"metroCode":"DC",

  "notifications":["test@gmail.com"],

  "virtualDeviceName":"Test-device-006-SROY - secondary",

  "additionalBandwidth":"200",

  "sshUsers":[{"action":"CREATE","sshUsername":"mekana12","sshPassword":"Mekana123"},{"action":"REUSE","sshUserUuid":"72902689-dff7-437d-8832-4bc8f3495252"},

  {"action":"REUSE","sshUserUuid":"a394dee9-d71d-4446-9210-c948cdd18a4b"}],

  "acl":["10.10.10.2/32","10.10.10.1/32"],

  "accountNumber":"2252619"},

  "additionalBandwidth":"100"

}'

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Possible Values Description
draft No boolean False True, False Default=false. To save a draft, set draft=true. You must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode to save a draft. sshUsers and licenseFileId information will not be saved for drafts. Also, this API will not do access control list validation when you save a draft. 
draftUUID No string ec68e425-f973-452e-a866-76be5844d0ba   To create a device from a draft that you saved earlier, provide the unique Id of the draft (draftUUID). 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Possible Values Description
deviceTypeCode Yes string CSR1000V

 

Virtual device type (device type code).
accountNumber No string 10478397

 

Account number. Either an account number or an account referenceId is required to create a virtual device. 
accountReferenceId No string 791281   Account reference Id. This is a temporary ID that can be used to create a device when your account is still pending, not active. Either an account number or an account referenceId is required to create a virtual device. 
hostNamePrefix Yes string mySR   Host name prefix. This gets included as part of an FQDN that ensures that the device is reachable from approved sources, if desired. Only a-z, A-Z, 0-9 and hyphen(-) are allowed. It should start with a letter and end with a letter or a digit. Also, it should be minimum 2 and maximum 10 characters long. 
virtualDeviceName Yes string CiscoSTROY   Virtual device name for identification. This should be minimum 3 and maximum 50 characters long. 
licenseFileId No string 6651aef5-e738-411f-8675-5f6b7b9cd429   License file Id is mandatory for some vendors-devices. If you select subscription license model (SUB), then you do not need to provide a licenseFileId. For Cisco HA devices, you must upload two different license files. For Juniper HA devices, you may use the same license file for both the devices. 
licenseMode Yes string BYOL BYOL, SUB License type. One of SUB (subscription) or BYOL (bring your own license) from your vendor. 
licenseToken No string V74191621   License token is mandatory for some vendor-devices that provide/accept a license token. You do not need to provide a license token if you want a subscription model or if your vendor provides license files. This field must have 8 alphanumeric characters. For Palo Alto HA (high availability) devices, you may provide just one or two different tokens. 
metroCode Yes string SV   Metro code. You may provide two different metros for your HA device. 
notifications Yes array test1@example.com   Email addresses for device life-cycle notification. We need a minimum of 1 and no more than 5 email addresses. You may have a different notification list for your HA device that has a secondary device for high availability. 
packageCode Yes string VM100   Software package code. 
sshUsers No array[object] {
        "sshUserUuid": "",
        "action": "CREATE",
        "sshUsername": "cust00011_DCT",
        "sshPassword": "projPass!"
      }
  SSH users. You may have two distinct sets of ssh users in case you have an HA device with a secondary device for high availability. 
termLength No integer 24   Billing term length in months.
throughput No integer 500   Throughput. Mandatory for most devices, e.g. CSR1000V
ThroughputUnit No string Mbps   Throughput unit. Mandatory for most devices, e.g. CSR1000V.
acl No array[string] ["192.168.10.0/24"]   IP addresses, no more than 50, in CIDR format. You may have two distinct sets of ACLs in case you have an HA device with a secondary device for high availability.  
purchaseOrderNumber No string 3456789   Purchase order number. Optional field that customers can use to track this device creation to their own purchase order number. 
additionalBandwidth No integer 100   Additional bandwidth. You may have a different additional bandwidth for your secondary device in case you have an HA device. 
secondary No object secondary{}   Object containing the optional HA device details to create a secondary device for high availability. 
sshUserUuid No string ef673cd4-9fc2-4ab4-810e-7274aaf7bc2d   Required for DELETE, REUSE operations. In case you want to REUSE an existing user, please provide the unique Id of the user. 
action No string CREATE CREATE, DELETE, REUSE Action to be performed. 
sshUsername No string cust00011_DCT   SSH Username
sshPassword No string projPass!   SSH Password

 

Sample response for a non-HA device.

 

{
    "uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec"
}

 

Sample response for a virtual device with an additional secondary device for high availability.

 

{
    "uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec",
    "secondaryUUID": "de5cf79b-3d16-4ccd-841b-3b68ecda2142"
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
uuid string b43ba509-a7d9-4334-8dee-dc4f29bf2e77 Unique identifier of the virtual device.
secondaryUUID string 92c2e49d-2c35-432d-a9af-016920bef70c Unique identifier of the secondary virtual device (HA).

 

 

When a device is created, the device transitions through various states within the Equinix infrastructure. These states can be monitored using the "status" response attribute of the Get virtual device {UUID} API. Your device must be provisioned and your license must be registered before you can use this virtual device to connect to cloud service providers and take advantage of other services like BGP peering and VPN termination. 

 

Virtual device "status"  Description
INITIALIZING Equinix is in the process of reserving resources and creating the device.
PENDING_ACCOUNT Customer's account is not approved. The device creation will continue once the account gets approved.
PROVISIONING Device is booting.
WAITING_FOR_PRIMARY The secondary device is ready but the primary is not. This state might appear only if you have requested a secondary device for high availability (HA). 
WAITING_FOR_SECONDARY The primary device is ready but the secondary is not. This state might appear only if you have requested a secondary device for high availability (HA). 
FAILED Device creation failed. 
PROVISIONED Device is ready. 

 

 

When an end-user deletes a device using the DELETE virtual device API,  the device transitions through the following states within the Equinix infrastructure. 

 

Virtual device "status" under /ne/v1/device/{uuid} Description
DEPROVISIONING Equinix accepted customer's request to delete virtual device. 
DEPROVISIONED Device is deprovisioned/deleted. 

 


body: 
Sample payloads for specific devices/licensing options

 

Parameter Name CSR1000V subscription CSR1000V BYOL Juniper Palo Alto Fortinet
deviceTypeCode CSR1000V CSR1000V VSRX PA-VM FG-VM
hostNamePrefix myHost123 myHost123 myHost123 myHost123 myHost123
licenseMode Sub BYOL BYOL BYOL BYOL
licenseToken       6789992  
licenseFileId   cf92ee6f-286f-496e-b4a1-7b4d1802109e cf92ee6f-286f-496e-b4a1-7b4d1802109e   cf92ee6f-286f-496e-b4a1-7b4d1802109e
notifications test@equinix.com test@equinix.com test@equinix.com test@equinix.com test@equinix.com
metroCode DC DC DC DC DC
acl 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32
packageCode SEC SEC STD VM100 VM02
throughput 500 500 1 500  
throughputUnit Mbps Mbps Gbps Mbps  
virtualDeviceName myCiscoSubSR myCiscoByolSR myJuniperSR myPaloAltoSR myFortinetSR
accountNumber 1234567 1234567 1234567 1234567 1234567
action CREATE CREATE CREATE CREATE CREATE
sshUsername myTest myTest myTest myTest myTest
sshPassword myProjPass! myProjPass! myProjPass! myProjPass! myProjPass!
addtionalBandwidth 100 100 100 100 100
purchaseOrderNumber 888888 888888 888888 888888 888888

 


body: 
SSH user and ACL (Access IP address) management 

You can add ssh users and a list of ACL (Access IP addresses) at the time you create your virtual device. To manage the list of ssh users and ACLs for an existing virtual device, you have the following APIs:

 

   1)  GET SSH users

   2)  GET SSH user {uuid}

   3)  POST SSH user

   4)  DEL SSH user

   5)  PUT ACL

 

Refer to API Reference section for detailed instructions about these APIs or just click on the above links. 

 

 


body: 

Connect to Cloud Service Providers

   Connect to AWS          

   Connect to Azure          

   Connect to Google          

   Connect to Oracle

   Connect to other service providers

 


body: 

Connect to AWS

You can create a connection between your Equinix virtual device and AWS Direct Connect. 

 

Click here to watch a video on how to create a virtual device and connect to AWS using Network Edge Portal. 

 


body: 
How to establish an L2 connection to AWS?
 

 

What do you need to create a connection? 

 

     1) A provisioned Equinix virtual device (virtualDeviceUUID) with a registered license. In case you have an optional secondary virtual device, you also need the Id of the secondary device.

     2) Authorization key from your provider (account ID from AWS). In case you have an optional secondary virtual device, you also need an authorization key for your secondary device. The two authorization keys will be the same if they belong to the same account. 

     3) Unique Id of the provider's service profile (profileUUID), metro (sellerMetroCode), and region (sellerRegion) of the provider

 

If you already have all the information and authentication credentials, you can skip ahead to Step 2f and create a connection. Otherwise, go through the steps to retrieve information.

 

body: 
Step 1: Retrieve AWS Account Info

Locate your AWS account ID using the AWS Management console.

 

The AWS Account ID is a 12 - digit number and is essential for creating an AWS Direct Connect connection.

 

 


body: 
Step 2: Create Connection

2a) Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Network Edge platform, contact your local Equinix Service Desk. 

 

2b) Get virtual devices

Find out your available virtual devices on the NE platform and their unique Ids (UUIDs). Refer to Get virtual devices under the API Reference section for detailed instructions. You can only create connections for a provisioned virtual device with a registered license. 

 

You may skip this step if you already know your available virtual devices.

 

2c) Get metros

Find out metro regions (metroCodes) where the NE platform is available. Refer to Get metros under the API Reference section for detailed instructions. 

 

You may skip this step if you already know the metro code.  

 

 

2d) Get Service Profile

Identify all seller/service profiles available for a given metro or metros. Refer to Get L2 service profiles under the API Reference section to find profileUUID, sellerMetroCode, and sellerRegion.

 

You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether a connection can be established between your AWS Account Info and the seller profile selected earlier by calling Get validateAuthorizationKey API

 

You may skip this step if you are certain that your key is authorized for creating connections with the selected service profile.

 

2f) Post Connections

POST /ne/v1/l2/connections

Method POST
URL or End Point /ne/v1/l2/connections
Headers Authorization token, Content-Type
Query Parameters Not applicable
Body Parameters virtualDeviceUUID, primaryName, profileUUID, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, authorizationKey, secondaryVirtualDeviceUUID, secondaryName, secondarySpeed, secondarySpeedUnit, secondaryAuthorizationKey, secondarySellerMetroCode, secondarySellerRegion

 

The POST connections API creates a Layer 2 Connection between your virtual device and the destination service profile. 

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create a layer 2 AWS connection for HA and non-HA virtual devices.

 

AWS Connection for a non-high availability virtual device

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "8c2845e5-be83-4561-ba2b-a53a7e4cf5ec",
  "primaryName": "JohnDoe_AWS_1",
  "profileUUID": "3214888b-39b0-49ea-a232-005088dc9c84",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",

  "sellerRegion": "us-west-1",
  "sellerMetroCode": "SV",
  "authorizationKey": "123456789012"

}'

 

AWS Connection for a high availability virtual device 

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "8c2845e5-be83-4561-ba2b-a53a7e4cf5ec",
  "primaryName": "JohnDoe_AWS_1",
  "profileUUID": "3214888b-39b0-49ea-a232-005088dc9c84",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",

  "sellerRegion": "us-west-1",
  "sellerMetroCode": "SV",
  "authorizationKey": "123456789012",

  "secondaryVirtualDeviceUUID": "7c2845e5-be83-4561-ba2b-a53a7e4cf5ez",

  "secondaryName": "JohnDoe_AWS_2",

  "secondarySpeed": 50,

  "secondarySpeedUnit": "MB",

  "secondaryAuthorizationKey": "123456789012"
}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
virtualDeviceUUID Yes string 8c2845e5-be83-4561-ba2b-a53a7e4cf5ec   Unique ID of the virtual device.
primaryName Yes string JohnDoe_AWS_1   Name of the primary connection - An alpha-numeric 24 character string that can only include hyphens and underscores ('-' & '_').
profileUUID Yes string 999552b-39b0-49ea-a232-005088dc9c86   Unique identifier of the provider's service profile.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB

'MB'

''GB'

Unit of the speed or bandwidth.
notifications Yes array  JohnDoe@equinix.com   An array of email ids for notification. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 0987654321   An optional field to link the customer's purchase order number to Equinix, so the number gets reflected on the invoice.
sellerRegion Yes string us-west-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the virtual device is set as the default seller metro code. 
authorizationKey Yes string 123456789012   Authorization Key obtained from the provider. Example: Account ID from AWS.
secondaryVirtualDeviceUUID No string 9c2845e5-be83-4561-ba2b-a53a7e4cf5em   Mandatory in case you have a secondary (high availability) device. This field represents the unique ID of the secondary device.
secondaryName No string JohnDoe_AWS_2   Mandatory in case you have a secondary (high availability) device. This field represents the name of the secondary connection. An alpha-numeric 24 character string that can only include hyphens and underscores ('-' & '_').
secondarySpeed No integer 50   Speed/Bandwidth you would like to allocate to the optional secondary connection.
secondarySpeedUnit No string MB

'MB'

'GB'

Unit of the speed or bandwidth of the optional secondary connection.
secondaryAuthorizationKey No string 123456789013  

Authorization key obtained from the provider for the optional secondary connection. Example: Account ID from AWS.

secondarySellerRegion No string us-east-1   The region in which the secondary seller port resides.
secondarySellerMetroCode No string DC   Provider location where you would like to connect your secondary connection.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Sample response for a virtual device (non HA).

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7",

    "status": "SUCCESS"
}

 

Sample response for a virtual device with an additional secondary device for high availability (HA).

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7",

    "secondaryConnectionId": "8eadc6b3-a44c-4ce9-bdba-ead9d7789202",

    "status": "SUCCESS"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Connection created successfully Indicates the status of the API call.
primaryConnectionId string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID  of the connection established.
secondaryConnectionId string 8eadc6b3-a44c-4ce9-bdba-ead9d7789202

Optional secondary connection Id in case you have a secondary device for high availability (HA).

status string SUCCESS Successful transaction.

 

 

Connections transition through various states within the Equinix and AWS infrastructure. These states can be monitored using the response attributes of the  Get L2 connections {connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in AWS.

 

Equinix States AWS States
status providerStatus AWS Direct Connect State Description
PROVISIONING NOT_AVAILABLE   Connection request has not been yet sent to AWS.
PROVISIONED PENDING_APPROVAL 

Ordering -> Requested 

The connection awaits for acceptance.

 

 

You will see a card stating “Accept Hosted Connection”  on your ECXF - Portal dashboard.

 

PROVISIONED PROVISIONING Pending Connection establishment in progress.
PROVISIONED PROVISIONED Pending -> Available

The connection has been accepted by the client.

 

 

These status values will only be reflected after the below "Accept Connection" step is performed. 

 

 

Refer https://docs.aws.amazon.com/directconnect/latest/APIReference/API_Connection.html for the different AWS connection states.  

 

 

When an end-user deletes a connection using the DELETE Connections {uuid}  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States
status providerStatus Description

DEPROVISIONING

DEPROVISIONING

Connection disbandment in progress.

DEPROVISIONED DEPROVISIONED

Connection deleted.

 


body: 
Step 3: Accept Connection

Accept the virtual connection using AWS Management Console, Equinix Network Edge Portal, or the below API.

 

Patch Connections

PATCH /ne/v1/l2/connections/{connid}

 Method  PATCH
 URL or End Point  /ne/v1/l2/connections/{connId}
 Headers  Authorization, Content-Type
 Query Parameters  action
 Body Parameters  AWS Access Keys (Access Key ID and Secret Access Key)

 

ConnId is an identifier unique for each connection.

 

The PATCH connections API accepts or rejects an L2 connection for a given connection connID.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to accept an L2 connection and its respective JSON response. 

 

curl -X

PATCH "https://api.equinix.com/ne/v1/l2/connections/9999a8-0e07-44d0-944c-88a25d8d28f7?action=Approve"

-H "content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "accesskey":"AKIAGGJKJU7BC3QJKYQ",

  "secretkey":"CXGJW1lWbqENEqSkBAK"

}'

 

The description of the query parameters and the request payload is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
action Yes string Approve

"Approve"

"Reject"

The action to perform on the connection.
connId Yes string 9999a8-0e07-44d0-944c-88a25d8d28f7   The unique identifier of the connection.

 

Body Parameter Name Mandatory Type Example Description
accesskey Yes string AKIAGGJKJU7BC3QJKYQ Special keys provided by AWS to authenticate API requests.
secretkey Yes string CXGJW1lWbqENEqSkBAK Special keys provided by AWS to authenticate API requests.

 

{
    "message": "updated connection successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string updated connection successfully Indicates the status of the PATCH API call.
primaryConnectionID string primaryConnectionId: "9999a8-0e07-44d0-944c-88a25d8d28f7" Indicates the primary connection ID of the connection that was accepted.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Refer

https://docs.aws.amazon.com/directconnect/latest/UserGuide/getting_started.html for instructions on how to accept the connection using the AWS console.

 


body: 

Connect to Azure

You can create a connection between your Equinix virtual device and Azure Express Route. 

 

Click here to watch a video on how to to create a virtual device and connect to Azure using Network Edge Portal. 

 


body: 
How to establish an L2 connection to Azure?

 

 

What do you need to create a connection? 

 

     1) A provisioned Equinix virtual device (virtualDeviceUUID) with a registered license. In case you have an optional secondary virtual device, you also need the Id of the secondary device.

     2) Authorization key from your provider (account ID from AWS). In case you have an optional secondary virtual device, you also need the authorization key of the secondary device. The two authorization keys will be the same if they belong to the same account. 

     3) Unique Id of the provider's service profile (profileUUID), metro (sellerMetroCode), and region (sellerRegion) of the provider

 

If you already have all the information and authentication credentials, you can skip ahead to Step 2f and create a connection. Otherwise, go through the steps to retrieve information.

 


body: 
Step 1: Retrieve Microsoft Service Key

Obtain a location-specific service key via the Azure portal.

 

 


body: 
Step 2: Create Connection

2a) Authenticate

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

 

Refer to Generating a Client ID and Client Secret key section under the Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens section 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. 

 

2b) Get virtual devices

Find out your available virtual devices (UUIDs) on the NE platform by calling Get virtual devices API.

 

You may skip this step if you already know your available virtual devices.

 

2c) Get metros

Gather available metro options (metroCode) where the NE platform is available by calling Get metro  API.

 

You may skip this step if you already know the metro code where you want your device.  

 

2d) Get Service Profile

Identify all seller/service profiles available for a given metro or metros by calling Get L2 Service Profiles. You need profileUUID, sellerMetroCode and sellerRegion to create a connection.

 

You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether a connection can be established with your Azure service key and the seller profile selected in the previous step by calling Get validateAuthorizationKey API.

 

You may skip this step if you are certain that your key is authorized for creating connections with the desired service profile.

 

2f) Post Connections

POST /ne/v1/l2/connections

Method POST
URL or End Point /ne/v1/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters virtualDeviceUUID, primaryName, profileUUID, speed, speedUnit, notifications [...], purchaseOrderNumber,  secondaryVirtualDeviceUUID, secondaryName, secondarySpeed, secondarySpeedUnit,  namedTag, sellerMetroCode, authorizationKey

 

The POST connections API creates a Layer 2 Connection between your virtual device and the destination service profile. The authorization key is the only header that is passed to this API and a response is received based on the values passed.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show sample curl requests to create a layer 2 Azure connection for HA and non-HA virtual devices.

 

Azure Connection for a non-high availability virtual device

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "ecb215dc-0d1d-4a48-a150-aacad8d3a371",

  "primaryName": "JohnDoePrimary",

  "profileUUID": "274afb42-6d3a-4114-8f7e-717efee792ae",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "4562",

  "secondaryName": "JohnDoeSecondary",

  "namedTag": "Private",

  "sellerMetroCode": "DC",

  "authorizationKey": "fbc3c0e1-59e7-4bfe-b5f3-209dee6b692a"

}'

 

Azure Connection for a high availability virtual device

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "ecb215dc-0d1d-4a48-a150-aacad8d3a371",

  "primaryName": "JohnDoePrimary",

  "profileUUID": "274afb42-6d3a-4114-8f7e-717efee792ae",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "4562",

  "secondaryVirtualDeviceUUID": "03c2cfef-0ec2-4599-81c9-09efa0d7b0e7",

  "secondaryName": "JohnDoeSecondary",

  "secondarySpeed": 50,

  "secondarySpeedUnit": "MB",

  "namedTag": "Private",

  "sellerMetroCode": "DC",

  "authorizationKey": "fbc3c0e1-59e7-4bfe-b5f3-209dee6b692a"

}'

 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
virtualDeviceUUID Yes string ecb215dc-0d1d-4a48-a150-aacad8d3a371   Unique ID of the virtual device.
primaryName Yes string JohnDoe_Dot1q_Manual   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
profileUUID Yes string 84c6616c-573a-447d-a478-9fab8fff284d   Unique identifier of the provider's service profile.
speed Yes integer 50  

Speed/Bandwidth you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.

speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array  JohnDoe@equinix.com

 

An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 4562   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
secondaryVirtualDeviceUUID Yes string 03c2cfef-0ec2-4599-81c9-09efa0d7b0e7   The unique ID of the secondary virtual device. It is mandatory in case you have a secondary (high availability) device.
secondaryName Yes string JohnDoe2_Azure_QinQ   Name of the secondary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
secondarySpeed Yes string 50   Mandatory in case you have a secondary (high availability) device. Speed/Bandwidth you would like to allocate to the optional secondary connection.
secondarySpeedUnit Yes string MB

"MB"

"GB"

Mandatory in case you have a secondary (high availability) device. Unit of the speed or bandwidth of the optional secondary connection.
namedTag Yes string Private

"Private" 

"Public" 

"Microsoft" 

"Manual"

The type of peering you would like to set up with Azure Express Route.
sellerMetroCode Yes string DC   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code.  
authorizationKey Yes string fbc3c0e1-59e7-4bfe-b5f3-209dee6b692a   Authorization Key obtained from the provider. Example: Service Key from Azure Express Route, Account ID from AWS, Pairing Key from Google Cloud Platform, OCID from Oracle Cloud Infrastructure - they all map to the authorization key property.

 

NE Participants can create up to three connections to Azure using the same Azure service key. However, all 3 connections must have different namedTags such as "private", "public", "Microsoft" or "Manual"  peering. Note that "Microsoft" peering requires special permission from Microsoft.

 

Maximum Number Of Connections

Peering Type (indicated by namedTag field)

3  pairs (3 primary and 3 redundant) Public
Private
Microsoft
Manual

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Sample response for a virtual device (non HA).

 

{

    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9349a8-0e07-44d0-944c-88a25d8d28f7",

    "status": "SUCCESS"

}

 

 

Sample response for a virtual device with an additional secondary device for high availability (HA).

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9994b8d-dcdb-45bc-b760-55368e16f3c4",
    "secondaryConnectionId": "888d4c1-5444-4511-b2e4-51f06f062974"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionId string 9994b8d-dcdb-45bc-b760-55368e16f3c4 Indicates the primary connection ID of the connection that was just created.
secondaryConnectionId string 888d4c1-5444-4511-b2e4-51f06f062974 Indicates the secondary connection ID of the connection that was just created.

 

When a connection is created, the connection transitions through various states within the Equinix and Azure infrastructure. These states can be monitored using the response attributes of the API Get L2 connections {connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in Azure.

 

Equinix States  Azure States  
status providerStatus Provider Status Peerings Status Description
1. PROVISIONING NOT_AVAILABLE Not provisioned Not provisioned   Connection request has not been yet sent to Microsoft Azure.
2. PENDING_BGP_PEERING PENDING_BGP Provisioned Not provisioned

The connection has been approved and awaits for the customer to configure Microsoft peering on the Azure portal.

 

 

Note that the status will be “PENDING_BGP_PEERING” until peering is completed in the Azure portal and the status will only change to "PROVISIONED" once ECX Fabric syncs with Microsoft. If you want to synchronize the BGP peering instantly, you may use the Equinix Fabric Exchange portal.

3. PROVISIONING  PROVISIONED Provisioned Provisioned Provisioning completed at Microsoft's end and the connection is provisioning at Equinix's end.
4. PROVISIONED PROVISIONED Provisioned Provisioned The connection is provisioned.

 

 

 

 

When an end-user deletes a connection using the  API Delete connections {uuid}  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ne/v1/l2/connections/{connId}
status providerStatus Description

DEPROVISIONING

PROVISIONED

Connection disbandment in progress.

DEPROVISIONED DEPROVISIONED

Connection deleted.

 


body: 
Step 3: Setup Microsoft Peering

Configure BGP peering on the Azure portal and call the below API to synchronize the peering changes with Equinix. Once it is completed, the connection status retrieved via the Connections API should change from “Pending-BGP-Peering” to “Provisioned”

Alternatively, you can also synchronize the peering using the Equinix portal.

 

Refer to https://docs.microsoft.com/en-us/azure/expressroute/expressroute-howto-routing-portal-resource-manager for instructions on how to configure peering for an Express Route connection. 

 

Patch L2 Connections

PATCH l2/connection/bgpSync

 Method  PATCH
 URL or End Point  /ne/v1/l2/connection/bgpSync
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body Parameters  authorizationKey

 

The PATCH connections API synchronizes the peering changes done in the Azure portal with Equinix.

 

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

 

The following screenshots show a sample curl request to accept an L2 connection and its respective JSON response. 

 

curl -X

PATCH "http://api.equinix.com/ne/v1/l2/connection/bgpSync"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "authorizationkey": "ASDFGH9JK0LMNBVCXZ"

}'

 

The description of the request payload is as follows:

 

Body Parameter Name Mandatory Type Example values Description
authorizationkey Y string ASDFGH9JK0LMNBVCXZ Connection credentials such as Account ID for AWS, Service key for Azure, etc.

 

{
    "message": "Bgp Peering was Initiated, connection will be updated shortly "
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Bgp Peering was Initiated, connection will be updated shortly  Status of the Patch API call.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Refer

https://docs.aws.amazon.com/directconnect/latest/UserGuide/getting_started.html for instructions on how to accept the connection using the AWS console.

https://ecxfabric-documentation.equinix.com/hc/en-us for instructions on how to accept the connection using the Equinix Cloud Exchange Fabric Portal.

Patch L2 Connections {connId}

 


body: 

Connect to Google

You can create a connection between your Equinix virtual device and Google cloud platform. 

 

Click here to watch a video on how to create a virtual device and connect to GCP using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish an L2 connection to Google?

 

 

What do you need to create a connection? 

 

     1) A provisioned Equinix virtual device (virtualDeviceUUID) with a registered license. In case you have an optional secondary virtual device, you also need the Id of the secondary device.

     2) Authorization key from your provider (account ID from AWS). In case you have an optional secondary virtual device, you also need the authorization key of the secondary device. The two authorization keys will be the same if they belong to the same account. 

     3) Unique Id of the provider's service profile (profileUUID), metro (sellerMetroCode), and region (sellerRegion) of the provider

 

If you already have all the information and authentication credentials, you can skip ahead to Step 2f and create a connection. Otherwise, go through the steps to retrieve information.

 


body: 
Step 1: Retrieve Google Pairing Key

Obtain your Google pairing key using the Google GCP portal.

 

The Google pairing key is a unique key essential for creating a Google GCP connection. For example, 2dfcdee7-b6f9-41d0-b98f-639151097693/us-west1/1. It comprises of three parts:

1. An alphanumeric key (2cfcdcc7-b6f9-41d0-b98f-639151099393)

2. Region (us-west1

3. Zone (1)

 

Ensure to connect to the region and zone indicated in your pairing key when creating a connection. For example, the above pairing key will only work for zone 1 connections.

 

Refer https://cloud.google.com/free/docs/gcp for instructions on how to signup for GCP. 

 


body: 
Step 2: Create Connection

2a) Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 

2b) Get virtual devices

Find out your available virtual devices on the NE platform by calling Get virtual devices .

 

You may skip this step if you already know your available virtual devices.

 

2c) Get Service Profile

Identify all seller/service profiles available for a given metro or metros by calling GET L2 Service Profiles.

 

You may skip this step if you already know the service profile details.

 

2d) Get ValidateAuthorizationKey

Verify whether a connection can be established between your Google pairing key and the seller profile zone selected earlier by calling Get L2 validate authorization key.

 

You may skip this step if you are certain that your key is authorized for creating connections with the selected service profile.

 

2e) Post Connections

POST /ne/v1/l2/connections

Method POST
URL or End Point /ne/v1/l2/connections
Headers

Authorization, Content-Type

Query Parameters Not applicable
Body Parameters virtualDeviceUUID, primaryName, profileUUID, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, authorizationKey, secondaryVirtualDeviceUUID, secondaryName, secondaryprofileUUID, secondarySpeed, secondarySpeedUnit, secondaryNotifications, secondarySellerRegion, secondarySellerMetroCode, secondaryAuthorizationKey

 

The POST connections API creates a Layer 2 Connection between your virtual device and the destination service profile. 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 key, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create a layer 2 GCP connection for HA and non-HA virtual devices.

 

GCP Connection for a non-high availability virtual device

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "ecb215dc-0d1d-4a48-a150-aacad8d3a371",  

  "primaryName": "JohnDoeGoogle1",

  "profileUUID": "e0780ad2-adbb-49f8-b750-391dcf59236c",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "johnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "78921",

  "sellerRegion": "us-west1",

  "sellerMetroCode": "DC",

  "authorizationKey": "ec76e25d-89c3-47b3-814f-39916b4aa85e/us-west1/1"

}'

 

GCP Connection for a high availability virtual device connecting to the same or different zones

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "ecb215dc-0d1d-4a48-a150-aacad8d3a371",  

  "primaryName": "JohnDoeGoogle1",

  "profileUUID": "e0780ad2-adbb-49f8-b750-391dcf59236c",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "johnDoe@equinix.com"

  ],

  "sellerRegion": "us-west1",

  "sellerMetroCode": "DC",

  "purchaseOrderNumber": "78921",

  "authorizationKey": "ec76e25d-89c3-47b3-814f-39916b4aa85e/us-west1/1",

  "secondaryVirtualDeviceUUID": "03c2cfef-0ec2-4599-81c9-09efa0d7b0e7",

  "secondaryName": "JohnDoeGoogle2",

  "secondaryProfileUUID": "c60ebeab-8cc2-4d83-8b2a-a45bacd0d805",

  "secondarySpeed": 200,

  "secondarySpeedUnit": "MB",

  "secondaryNotifications": [

    "johnDoe@equinix.com"

  ],

  "secondarySellerRegion": "us-east1",

  "secondarySellerMetroCode": "DC",

  "secondaryAuthorizationKey": "5007a216-0014-43b3-b11c-8396f504aa62/us-west1/2"

}'

 

When creating a secondary connection from an (HA) device to GCP, you can either connect to the same profile zone or different profile zone.

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
virtualDeviceUUID Yes string ecb215dc-0d1d-4a48-a150-aacad8d3a371   Unique ID of the virtual device.
primaryName Yes string JohnDoe_GCP_QinQ   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
profileUUID Yes string 999552b-39b0-49ea-a232-005088dc9c86   Unique identifier of the provider's service profile.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerRegion Yes string us-west-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 
authorizationKey Yes string c13d9edf-ee52-42b0-gf3y-889a7a65fe9e/us-west1/1   Authorization Key obtained from Google. It also indicates the destination zone and region of the connection.
secondaryVirtualDeviceUUID No string 03c2cfef-0ec2-4599-81c9-09efa0d7b0e7   The unique ID of the secondary virtual device. It is mandatory in case you have a secondary (high availability) device.
secondaryName No string JohnDoeGoogle2   Mandatory in case you have a secondary (high availability) device. This field represents the name of the secondary connection. An alpha-numeric 24 character string that can only include hyphens and underscores ('-' & '_').
secondaryProfileUUID No string c60ebeab-8cc2-4d83-8b2a-a45bacd0d805   Mandatory in case you have a secondary (high availability) device. Unique identifier of the secondary service profile to which the secondary connection is connected to.
secondarySpeed No integer 50   Mandatory in case you have a secondary (high availability) device. Speed/Bandwidth you would like to allocate to the optional secondary connection.
secondarySpeedUnit No string MB

"MB"

"GB"

Mandatory in case you have a secondary (high availability) device. Unit of the speed or bandwidth of the optional secondary connection.
secondaryNotifications No string JohnDoe@equinix.com   An array of email ids you would like to notify when there are any updates on your secondary connection. 
secondarySellerRegion No string us-east1   Mandatory in case you have a secondary (high availability) device. Indicates the region in which the seller resides.
secondarySellerMetroCode No string DC   Mandatory in case you have a secondary (high availability) device. Provider location where you would like your secondary connection to connect. 
secondaryAuthorizationKey No string 5007a216-0014-43b3-b11c-8396f504aa62/us-west1/2   Mandatory in case you have a secondary (high availability) device. Authorization key obtained from the provider for the optional secondary connection. Example: OCID from Oracle Cloud Infrastructure.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Sample response for a virtual device (non HA).

 

{
    "message": "Connection Saved Successfully",

    "primaryConnectionId": "934629-dfbf-4a0a-94fe-a426f0b0606e",

}

 

Sample response for a virtual device with an additional secondary device for high availability (HA).

 

{
    "message": "Connection Saved Successfully",

    "primaryConnectionId": "0f5ddc89-dfbf-4a0a-94fe-a426f0b0606e",

    "secondaryConnectionId": "ef8af73c-8e72-4515-ac6c-2aeb60fda548"

}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 0f5ddc89-dfbf-4a0a-94fe-a426f0b0606e Indicates the primary connection ID.
secondaryConnectionID string ef8af73c-8e72-4515-ac6c-2aeb60fda548 Indicates the secondary connection ID.

 

When a connection is created, the connection transitions through various states within the Equinix and Google infrastructure. These states can be monitored using the response attributes of the API Get L2 connections {connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in Google.

 

Equinix States Google States
status providerStatus Google GCP State Description
PROVISIONING NOT_AVAILABLE   Connection request has not been yet sent to Google.
PROVISIONED PENDING_APPROVAL

Waiting for service provider

The connection awaits for acceptance.

PROVISIONED PROVISIONING Activation needed -> BGP Configuration needed Connection establishment in progress.
PROVISIONED PROVISIONED Pending -> Available The connection has been accepted by the client.

 

Refer https://cloud.google.com/interconnect/docs/concepts/dedicated-overview for the different GCP connection states.  

 

 

When an end-user deletes a connection using the  API  Delete Connections {uuid},  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States
status providerStatus Description

DEPROVISIONING

DEPROVISIONING

Connection disbandment in progress.

 

DEPROVISIONED DEPROVISIONED

Connection deleted.

 


body: 
Step 3: Activate Connection

Activate the virtual connection using Google Cloud Portal.

 

Refer to https://cloud.google.com/free/docs/gcp for instructions on how to activate the connection using Google Cloud Platform Console.

 


body: 

Connect to Oracle

You can create a connection between your Equinix virtual device and Oracle FastConnect. 

 

Click here to watch a video on how to create a virtual device and connect to Oracle FastConnect using Network Edge Portal. 

 


body: 
How to establish an L2 connection to Oracle?

 

 

What do you need to create a connection? 

 

     1) A provisioned Equinix virtual device (virtualDeviceUUID) with a registered license. In case you have an optional secondary virtual device, you also need the Id of the secondary device.

     2) Authorization key from your provider (account ID from AWS). In case you have an optional secondary virtual device, you also need the authorization key of the secondary device. The two authorization keys will be the same if they belong to the same account. 

     3) Unique Id of the provider's service profile (profileUUID), metro (sellerMetroCode), and region (sellerRegion) of the provider

 

If you already have all the information and authentication credentials, you can skip ahead to Step 2f and create a connection. Otherwise, go through the steps to retrieve information.

 


body: 
Step 1: Retrieve Oracle OCID

Obtain your Oracle OCID using the Oracle portal.

 

The OCID is a unique key essential for creating an Oracle FastConnect connection. 

 

Refer to https://docs.cloud.oracle.com/iaas/Content/Network/Concepts/fastconnectprovider.htm for instructions on how to signup for Oracle FastConnect. 

 


body: 
Step 2: Create Connection

2a) Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 

2b) Get virtual devices

Find out your available virtual devices on the NE platform by calling Get virtual devices. Unique Id (UUID) of your device is required to create a connection.

 

You may skip this step if you already know your available virtual devices.

 

2c) Get metros

Call Get metro API to find out your available metro options (metroCodes) where the NE platform is available.

 

You may skip this step if you already know where you want your device.  

 

2d) Get Service Profile

Identify all seller/service profiles available for a given metro or metros. Refer to Get L2 service profiles under the API Reference section to find profileUUIDsellerMetroCode, and sellerRegion.

 

You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether a connection can be established between your Oracle OCID service key and the seller profile selected earlier by calling Get validateAuthorizationKey API.

 

You may skip this step if you are certain that your key is authorized for creating connections with the selected service profile.

 

2f) Post Connections

POST /ne/v1/l2/connections

Method POST
URL or End Point /ne/v1/l2/connections
Headers

Authorization, Content-Type

Query Parameters Not applicable
Body Parameters virtualDeviceUUID, primaryName, profileUUID, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, authorizationKey, secondaryvirtualDeviceUUID, secondaryName, secondarySpeed, secondarySpeedUnit, secondaryAuthorizationKey

 

The POST connections API creates a Layer 2 Connection between your virtual device and the destination service profile. 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 key, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create a layer 2 Oracle connection for HA and non-HA virtual devices.

 

Oracle Connection for a non-high availability virtual device

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "6c2845e5-be63-4261-ba1c-a53a7e4cf5ec",
  "primaryName": "JohnDoeOracle1",
  "profileUUID": "d7f5769b-9618-4d8e-b7dc-9e68ffd0a8b8",
  "speed": 1,
  "speedUnit": "GB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "456299",
  "sellerRegion": "us-ashburn-1",
  "sellerMetroCode": "DC",

  "authorizationKey": "ocid1.virtualcircuit.oc1.iad.aaaaaaaafzx4jybgymnyfjfwyxl7f4b6emvp3uast2opcf6z7xzp2lqcnpjq"
}'

 

Oracle Connection for a high availability virtual device

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "4c2345e5-be63-4261-ba1c-a53a7e4cf5ec",
  "primaryName": "JohnDoeOracle1",
  "profileUUID": "c7f5469b-9618-4d8e-b7dc-9e643rd0a8b8",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1111",
  "sellerRegion": "us-ashburn-1",
  "sellerMetroCode": "DC",

  "authorizationKey": "ocid1.virtualcircuit.oc1.iad.aaaaabcdp2mwua7njveex3vmhchwqwyzzka5zrrhbo4wc7uz46pzlqghkzgq",

  "secondaryVirtualDeviceUUID": "7c2845e5-be83-4561-ba2b-a53a7e4cf5ez",

  "secondaryName": "JohnDoeOracle2",

  "secondarySpeed": 50,

  "secondarySpeedUnit": "MB",

  "secondaryAuthorizationKey": "ocid1.virtualcircuit.oc1.iad.sadffgp2mwua7njveex3vmhchwqwyzzka5zrrhbo4wc7uz46pzlqghkzgq"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
virtualDeviceUUID Yes string 4c2345e5-be63-4261-ba1c-a53a7e4cf5ec   Unique ID of the virtual device.
primaryName Yes string JohnDoeOracle1   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
profileUUID Yes string c7f5469b-9618-4d8e-b7dc-9e643rd0a8b8   Unique identifier of the provider's service profile.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB

"MB"

"GB"

Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerRegion Yes string us-ashburn-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 
authorizationKey Yes string ocid1.virtualcircuit.oc1.iad.aaafsderteyrt   Authorization Key obtained from the provider. Example: Service Key from Azure Express Route, Account ID from AWS, Pairing Key from Google Cloud Platform, OCID from Oracle Cloud Infrastructure.
secondaryVirtualDeviceUUID No string 7c2845e5-be83-4561-ba2b-a53a7e4cf5ez  

The unique ID of the secondary virtual device. It is mandatory in case you have a secondary (high availability) device.

secondaryName No string JohnDoeOracle2   Mandatory in case you have a secondary (high availability) device. This field represents the name of the secondary connection. An alpha-numeric 24 character string that can only include hyphens and underscores ('-' & '_').
secondarySpeed No integer 50   Mandatory in case you have a secondary (high availability) device. Speed/Bandwidth you would like to allocate to the optional secondary connection.
secondarySpeedUnit No string MB

"MB"

"GB"

Mandatory in case you have a secondary (high availability) device. Unit of the speed or bandwidth of the optional secondary connection.
secondaryAuthorizationKey No string ocid1.virtualcircuit.oc1.iad.sadffgp2mw   Mandatory in case you have a secondary (high availability) device. Authorization key obtained from the provider for the optional secondary connection. Example: OCID from Oracle Cloud Infrastructure.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Sample response for a virtual device (non HA).

 

{

    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9349a8-0e07-44d0-944c-88a25d8d28f7",

    "status": "SUCCESS"

}

 

Sample response for a virtual device with an additional secondary device for high availability (HA).

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "939a8-0e07-44d0-944c-86a25d8d38f7",

    "secondaryConnectionId": "7eadc4b3-a44c-4ce9-bdba-ead6d7789342",

    "status": "SUCCESS"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Connection created successfully Indicates the status of the API call.
primaryConnectionId string 939a8-0e07-44d0-944c-86a25d8d38f7 Indicates the primary connection ID  of the connection established.
secondaryConnectionId string 7eadc4b3-a44c-4ce9-bdba-ead6d7789342

Optional secondary connection Id in case you have a secondary device for high availability (HA).

status string SUCCESS A message indicating the status of the transaction. 

 

When a connection is created, the connection transitions through various states within the Equinix and Oracle infrastructure. These states can be monitored using the response attributes of the API Get connections {connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in Oracle.

 

Equinix States
status providerStatus Description
PROVISIONING NOT_AVAILABLE Connection request has not been yet sent to Oracle.
PROVISIONED PROVISIONING

Connection awaits for acceptance. Connection establishment in progress.

PROVISIONED PROVISIONED Connection established

 

 

When an end-user deletes a connection using the Delete connections {uuid} API,  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ne/v1/l2/connections/{connId}
status providerStatus Description

DEPROVISIONING

DEPROVISIONING

Connection disbandment in progress.

DEPROVISIONED DEPROVISIONED

Connection deleted.

 

 

 

 


body: 

Connect to other service providers

End users can create connections to other Equinix customers (customers, vendors, and partners) using either a Dot1Q port or a QinQ port. 

 

Click here to watch a video on how to connect to other Equinix customers using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish an L2 connection to other service providers?

 

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 


body: 
Step 2: Get Attribute Information

2a) Get virtual devices

Find out your available virtual devices on the NE platform by calling Get virtual devices API. You need the unique Id (UUID) of your device to create a connection.

 

You may skip this step if you already know your available virtual devices.

 

2b) Get metros

Find out the locations where the NE platform is available by calling Get metro API. You need the metroCode to create a connection.

 

You may skip this step if you already know the metro code.  

 

2c) Get Service Profile

Identify all seller/service profiles available for a given metro or metros by calling Get service profiles API. You need the profileUUIDsellerMetroCode, and sellerRegion to create a connection.

 

If you intend to create a connection to a private seller service profile, ensure that you have been authorized by the respective seller profile to access and retrieve the service profile details.

In order to do this, the seller must whitelist your email ID  by adding the email address to the private profile in the ECX portal.

For more information please refer to the ECX Fabric documentation at https://ecxfabric-documentation.equinix.com/hc/en-us/articles/360013214112-Setting-your-company-s-visibility

 

You may skip this step if you already know the service profile details.

 


body: 
Step 3: Create Connection

Post Connections

POST /ne/v1/l2/connections

Method POST
URL or End Point /ne/v1/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters

virtualDeviceUUID, primaryName, profileUUID, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, authorizationKey, secondaryvirtualDeviceUUID, secondaryName, secondarySpeed, secondarySpeedUnit, secondaryAuthorizationKey

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create a layer 2 enterprise connection for HA and non-HA virtual devices.

 

Enterprise Connection for a non-high availability virtual device

 
 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "6c2845e5-be63-4261-ba1c-a53a7e4cf5ec",
  "primaryName": "JohnDoeEnterprise1",
  "profileUUID": "d7f5769b-9618-4d8e-b7dc-9e68ffd0a8b8",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "456299",
  "authorizationKey": "xxxxxxxxx",
  "sellerMetroCode": "DC"

}'

 

Enterprise Connection for a high availability virtual device

 

curl -X

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "4c2345e5-be63-4261-ba1c-a53a7e4cf5ec",
  "primaryName": "JohnDoeEnterprise1",
  "profileUUID": "c7f5469b-9618-4d8e-b7dc-9e643rd0a8b8",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "456",
  "sellerMetroCode": "DC",

  "authorizationKey": "xxxxxxxxx",

  "secondaryVirtualDeviceUUID": "7c2845e5-be83-4561-ba2b-a53a7e4cf5ez",

  "secondaryName": "JohnDoeEnterprise2",

  "secondarySpeed": 50,

  "secondarySpeedUnit": "MB",

  "secondaryAuthorizationKey": "xxxxxxxxx"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
virtualDeviceUUID Yes string 4c2345e5-be63-4261-ba1c-a53a7e4cf5ec   Unique ID of the virtual device.
primaryName Yes string JohnDoeEnterprise1   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
profileUUID Yes string c7f5469b-9618-4d8e-b7dc-9e643rd0a8b8   Unique identifier of the provider's service profile.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB

"MB"

"GB"

Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 
authorizationKey No string xxxxxxxx   An optional field based on the service profile you want to connect to. 
secondaryVirtualDeviceUUID No string 7c2845e5-be83-4561-ba2b-a53a7e4cf5ez  

The unique ID of the secondary virtual device. It is mandatory in case you have a secondary (high availability) device.

secondaryName No string JohnDoeEnterprise2   Mandatory in case you have a secondary (high availability) device. This field represents the name of the secondary connection. An alpha-numeric 24 character string that can only include hyphens and underscores ('-' & '_').
secondarySpeed No integer 50   Mandatory in case you have a secondary (high availability) device. Speed/Bandwidth you would like to allocate to the optional secondary connection.
secondarySpeedUnit No string MB

"MB"

"GB"

Mandatory in case you have a secondary (high availability) device. Unit of the speed or bandwidth of the optional secondary connection.
secondaryAuthorizationKey No string xxxxxxxx   Mandatory in case you have a secondary (high availability) device. Authorization key obtained from the provider for the optional secondary connection. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Sample response for a virtual device (non HA).

 

{

    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9349a8-0e07-44d0-944c-88a25d8d28f7",

    "status": "SUCCESS"

}

 

Sample response for a virtual device with an additional secondary device for high availability (HA).

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "939a8-0e07-44d0-944c-86a25d8d38f7",

    "secondaryConnectionId": "7eadc4b3-a44c-4ce9-bdba-ead6d7789342",

    "status": "SUCCESS"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID.
secondaryConnectionId string 7eadc4b3-a44c-4ce9-bdba-ead6d7789342 Optional secondary connection Id in case you have a secondary device for high availability (HA).
status string SUCCESS A message indicating the status of the transaction. 

 

When a connection is created, the connection transitions through various states within the Equinix infrastructure. These states can be monitored using the response attributes of the API Get connections {connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status at the enterprise's end.

 

Equinix States under /ne/v1/l2/connections/{connId}
status providerStatus Description
PENDING_APPROVAL NOT_AVAILABLE Connection request has been sent to seller and is awating approval.

The seller must approve or reject the connection at this point or the "status" and "providerStatus" would remain unchanged.

PROVISIONING

or

REJECTED

NOT_AVAILABLE

Connection establishment in progress.

or

The seller has rejected the connection.

PROVISIONED AVAILABLE

Connection established.

 

 

When an end-user deletes a connection using the  API  Get L2 connections {connId}  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ne/v1/l2/connections/{connId}
status providerStatus Description
PENDING_DELETE AVAILABLE Deletion request has been sent to seller and is awating approval.

The seller must approve this delete request to disconnect the connection and to stop billing.  Keep in mind that should the seller fail to approve the deletion request, the connection would still be considered active and charged accordingly.

DEPROVISIONING

AVAILABLE

Connection disbandment in progress.

or

The seller has rejected the request.

DEPROVISIONED NOT_AVAILABLE

Connection deleted.

 


body: 

Establish BGP peering

 

 

A BGP session establishes a point-to-point connection between your virtual device and cloud service provider. To create BGP peers, you must have the following:

   1) A provisioned virtual device with a registered license. 

   2) A provisioned connection (connectionUUID). 

 

If you have the above then you can skip ahead to Step 4 and create BGP peers. Otherwise, follow the steps. 

 

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Network Edge, contact your local Equinix Service Desk. 

 


body: 

Step 2: Create/Get virtual devices

 

a) To create a virtual device, please follow these steps

b) To check the status of your virtual device, call Get virtual device {UUID} API or Get virtual devices API.

 

You may skip the above step if you have a provisioned device with a registered license.

 


body: 

Step 3: Create/Get connection

 

a) To connect to your cloud service providers, follow these steps. 

b) To check the status of your connections, call Get L2 connections {connId} API or Get L2 Buyer connections API. 

 

You may skip this step if you have a provisioned connection.

 


body: 

Step 4: Create BGP peering

   

POST /ne/v1/services/bgp

 Method  POST
 URL or End Point  /ne/v1/services/bgp
 Headers  Authorization token, Content-Type
 Query Parameters  Not applicable
 Body Parameters

 authenticationKey, connectionUUID, localAsn, localIpAddress, remoteAsn, remoteIpAddress

 

The POST bgp API creates a BGP session to establish a point-to-point connection between your virtual device and cloud service provider. 

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

A sample curl request to create BGP peering.

 

curl -X

POST "https://api.equinix.com/ne/v1/services/bgp"

-H "Authorization: Bearer CcYxLosIYIIsmCGav5pplU25dLkG"
-H "Content-Type: application/json"
-d '{
  "authenticationKey": "sroy001",
  "connectionUUID": "80afc8be-0ce3-4950-be27-3d3e678e6873",
  "localAsn": 10012,
  "localIpAddress": "10.0.0.1/29",
  "remoteAsn": 10013,
  "remoteIpAddress": "10.0.0.2"
}'

 

Body Parameter Name Mandatory Type Example Possible Values Description
authenticationKey No string pass123   Provide a key value that you can use later to authenticate.
connectionUUID Yes string f79eead8-b837-41d3-9095-9b15c2c4996d   UUID of the connection between the virtual device and the cloud service provider.
localAsn Yes integer 10012   Local ASN (autonomous system number). This is the ASN of your virtual device. 
localIpAddress Yes string 100.210.1.221/30   Local IP Address. This is the IP address of the virtual device in CIDR format.
remoteAsn Yes integer 10013   Remote ASN (autonomous system number). This is the ASN of the cloud service provider. 
remoteIpAddress Yes string 100.210.1.31   Remote IP address. This is the IP address of the cloud service provider.

 

Sample response:

 

{
    "uuid": "64e46bc1-fc2c-43b8-956e-213afe8f5d39"
}

 

Response parameter:

 

Field Type Example Values Description
UUID string   UUID of the BGP peering.

 

After you create BGP peering, you can check the status of your BGP peering by calling GET BGP configuration {bgpuuid} or GET BGP configuration {connUUID}.

 

BGP provisioningStatus Description
PROVISIONING BGP peering is provisioning.
PROVISIONED BGP peering is provisioned.
FAILED BGP peering failed.

 

Possible BGP states: Idle, Connect, Active, Established, OpenSent, and OpenConfirm.

 

The BGP states can be only be seen after the BGP is provisioned.

 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

Establish VPN connectivity

 

 

A VPN configuration uses an IPSec tunnel and an associated BGP to allow a remote site to receive traffic originating from clouds connected to the data interfaces of your virtual device. 

 

Refer Network Edge VPN tunnels and sites for more information 

 

To create a VPN you must have:

 

   1) A provisioned virtual device with a registered license and access control list (ACLs).  Call Get virtual devices to check the status of your devices and find the virtualDeviceUUID

   2) At least one provisioned connection with provisioned BGP peering.  To check the details of your connection, call Get L2 buyer connections. To check the status of your BGP peering, call Get BGP {bgpuuid} or Get BGP configuration {connUUID}

   3) If you have a secondary device for high availability (HA), you also need to provide secondary VPN details.

 

If you have the above then you can skip ahead to Step 4 and create a VPN. Otherwise, follow the steps. 

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Network Edge, contact your local Equinix Service Desk. 

 


body: 

Step 2: Create/Get virtual devices

 

a) To create a virtual device, please follow these steps

b) To check the status of your virtual device, call Get virtual device {uuid} API or Get virtual devices API.

 

You may skip the above step if you have a provisioned device with a registered license.

 


body: 

Step 3: Create/Get connection with BGP

 

a) To connect to your cloud service providers and setup  BGP peering, follow these steps

b) To check the status of your connections, call GET connection by UUID API or GET L2 Buyer connections API. 

c) To check the status of your BGP peering, call GET BGP {bgpUUID} or GET BGP configuration {connUUID}

 

You may skip this step if you have a provisioned connection with BGP peering.

 


body: 

Step 4: Create VPN

 

POST /ne/v1/services/vpn

 Method  POST
 URL or End Point  /ne/v1/services/vpn
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body Parameters

 siteName, virtualDeviceUUID, configName, peerIp, peerSharedKey, remoteAsn

 remoteIpAddress, password, localAsn, tunnelIp, secondary   {configName, peerIp, peerSharedKey, remoteAsn, remoteIpAddress, password,

 localAsn, tunnelIp}

 

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

 

Sample curl request to create VPN configuration for a virtual device (non HA). 

 

curl -X

POST "https://api.equinix.com/ne/v1/services/vpn"

-H "Authorization: Bearer 4P8uH5ZWsgH4qlovBrFZG4Hzpp2V"
-H "Content-Type: application/json"
-d '{
  "siteName": "Chicago",
  "virtualDeviceUUID": "8c2845e5-be83-4561-ba2b-a53a7e4cf5ec",
  "configName": "Traffic from AWS cloud",
  "peerIp": "110.11.12.222",
  "peerSharedKey": "5bb2424e888bd",
  "remoteAsn": 65413,
  "remoteIpAddress": "100.210.1.31",
  "password": "pass123SROY",
  "localAsn": 65414,
  "tunnelIp": "192.168.7.2/30"
}'

 

Sample curl request to create VPN configuration for a virtual device with a secondary device for high availability (HA). 

 

curl -X

POST "https://api.equinix.com/ne/v1/services/vpn"

-H "Authorization: Bearer 4P8uH5ZWsgH4qlovBrFZG4Hzpp2V"
-H "Content-Type: application/json"
-d '{
  "siteName": "Chicago",
  "virtualDeviceUUID": "8c2845e5-be83-4561-ba2b-a53a7e4cf5ec",
  "configName": "Traffic from AWS cloud",
  "peerIp": "110.11.12.222",
  "peerSharedKey": "5bb2424e888bd",
  "remoteAsn": 65413,
  "remoteIpAddress": "100.210.1.31",
  "password": "pass123SROY",
  "localAsn": 65414,
  "tunnelIp": "192.168.7.2/30",
  "secondary": {
    "configName": "Traffic from AWS cloud-SROY",
    "peerIp": "110.11.12.222",
    "peerSharedKey": "5bb2424e888bd",
    "remoteAsn": 65413,
    "remoteIpAddress": "100.210.1.31",
    "password": "pass123SROY",
    "localAsn": 65414,
    "tunnelIp": "192.168.7.2/30"
  }
}'

 

Description of request body parameters:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
siteName Yes string Chicago  

Your remote siteName. This must be unique and between 2 and 10 alphanumeric characters long with no spaces. 

virtualDeviceUUID Yes string f79eead8-b837-41d3-9095-9b15c2c4996d  

UUID of the virtual device. This must be 36 characters long.

configName Yes string Traffic from AWS cloud   Description of the VPN. This must be between 3 and 50 characters. If your device is an HA device that has a secondary device for high availability, you must provide a secondary config name.
peerIp Yes string 100.210.1.221  

IP Address of the remote site to which you are connecting (this is on the customer side). You must provide a unique peer IP address for every VPN between a virtual device and the remote site. 

peerSharedKey Yes string 10013   Pre-shared key for VPN.
remoteAsn Yes string 10023   Remote ASN (autonomous system number). Remote ASN and local ASN cannot be the same. You cannot use the following reserved ASN numbers: 0, 23456, 64496-64511, 65535, 65552-131071, 4294967295. 
remoteIpAddress Yes string 100.210.1.31   Remote IP address to establish BGP peering (this is on the customer side).
password Yes string pass123SROY   Password for BGP peering. This must not start with a number, must be between 4 and 25 characters long, and contain only alphanumeric characters.
localAsn Yes interger 65414   Local ASN (autonomous system number) of Equinix site. Remote and local ASN cannot be the same. You cannot use the following reserved ASN numbers: 0, 23456, 64496-64511, 65535, 65552-131071, 4294967295. 
tunnelIp Yes string 192.168.7.2/30   Local tunnel IP in CIDR format.

 

Sample VPN configuration response (no HA device).

 

{
    "vpnUuid": "eb26b601-02cc-4473-b1ee-3e2d4d847315"
}

 

Sample VPN configuration response for a virtual device with a secondary virtual device for high availability.

 

{
    "secondaryVpnUuid": "991b775a-16ec-4f2e-b861-8ab93a39902a",
    "vpnUuid": "eb26b601-02cc-4473-b1ee-3e2d4d847315"
}

 

Description of the response payload:

 

Field Type Example Values Description
vpnUuid string 991b775a-16ec-4f2e-b861-8ab93a39902a Unique Id of the VPN on the primary device.
secondaryVpnUuid string eb26b601-02cc-4473-b1ee-3e2d4d847315 Unique Id of the VPN on the secondary device.

 

After you create a VPN configuration, you can check the status of your VPN by calling Get VPN.

 

Possible VPN status Description
PROVISIONING VPN is provisioning.
PROVISIONED VPN is provisioned.
FAILED VPN provisioning failed.
DEPROVISIONING VPN is deprovisioning.
DEPROVISIONED VPN is deprovisioned

 

VPN tunnel status is either UP or DOWN.

 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

Create and launch SDWAN devices

To create SDWAN devices, you must know the following:

1) Which SDWAN device (deviceTypeCode) you want, what software type (packageCode) you need, and the location where you want your SDWAN device (metroCode). 

2) Equinix account number with the account status in Active or Pending state. 

3) The process to bring your own license (BYOL) from your vendor. Check Step 3 for detailed instructions. 

4) ACLs.

   a) For Cisco SDWAN, you must get the IP addresses of vBond, vManage, and vSmart servers so you can whitelist them within Equinix (as ACLs) when creating an SDWAN device. 

 

Refer to Provisioning Cisco cEdge SD-WAN for details.

   

   b) For CloudGenix, you must get IP addresses from CloudGenix portal to whitelist them within Equinix (as ACLs) when creating an SDWAN device. 

 

If you have all the necessary information, then skip ahead to Step 4 and create SDWAN devices. Otherwise, follow the steps:

 

If you do not have all the necessary information, you can still save as a draft. You must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode to save a draft.

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 Network Edge, contact your local Equinix Service Desk. 

 


body: 
Step 2: Get device types

 

2a) Get device types

 

Call Get device types  API to find out SDWAN devices you can launch on the NE platform. You will learn about metros (metroCode) where these devices are available, available software packages, and all possible licensing and throughput options. 

 

You may skip this step if you already know which device you want.

 

2b) Get account

 

Check your account number (or acountReferenceId) and status in the metro where you want a virtual device by calling Get account API. For billing reasons, you must have an account in the metro where you want a virtual device, either in the Active or Pending state. To create an account go to accountcreateurl.

 

You may skip this step if you already know your account number (or accountReferenceId) and status.  

 


body: 
Step 3: Configure a license

For now, BYOL (bring your own license) is the only licensing option available for SDWAN devices and the process to BYOL is unique to every vendor. 

 

To configure a license for a CISCO SDWAN device, you must do the following:

  1) Generate a bootstrap file on Cisco vManage platform. 

  2) Upload the Cisco bootstrap file on Equinix platform by calling POST a license before creating a virtual device (BYOL). You'll get a licenseFileId that you can use to create a virtual SDWAN device. 

 

To configure a license for a CloudGenix device, you must do the following: 

   1) Generate a license key (ION key) and license secret (Secret key) on CloudGenix platform.

   2) Input the license key (ION key) and secret (Secret key) when calling Equinix create device API to create a CloudGenix SDWAN device. 


body: 
Step 4: Create SDWAN devices

POST /ne/v1/device

 Method  POST
 URL or End Point  /ne/v1/device
 Headers  Authorization, Content-Type
 Query Parameters  draft, draftUUID
 Body Parameters

 additionalBandwidth, deviceTypeCode, licenseFileId, licenseMode, metroCode, 

 notifications[...], packageCode, termLength,

 throughput, throughputUnit, vendorConfig{ }, virtualDeviceName, acl[...], accountNumber, accountReferenceId, 

 purchaseOrderNumber, secondary   {accountNumber, accountReferenceId, acl[...], additionalBandwidth, licenseFileId,

 metroCode, notifications[...], vendorConfig{ }, virtualDeviceName}}

 

Vendor config parameters for Cisco, CloudGenix, and Versa:

 

Cisco: CSRSDWAN

Cisco vendorConfig{ } parameters Mandatory Type Example Possible Values Description
siteId Yes string 12345   Site Id. Mandatory for Cisco SDWAN devices. A siteId is a particular physical location within the Viptela overlay network, such as a branch office, or a campus.
systemIpAddress Yes string 192.168.1.5   System IP address. Mandatory for Cisco SDWAN devices. Each vEdge router and vSmart controller is assigned a system IP address. It should be in decimal four-part dotted notation, just like IPv4 address. 

 

CloudGenix: CGENIXSDWAN

CloudGenix vendorConfig{ } parameters Mandatory Type Example Possible Values Description
licenseKey (ION key) Yes string 1404-991d81bb-2567-43e5-a14c-1493ace58046   License key (ION key). Mandatory for CloudGenix devices.
licenseSecret (Secret key) Yes string ec68e425-f973-452e-a866-76be5844d0ba   License secret (Secret key). Mandatory for CloudGenix devices. 

 

Versa: VERSA_SDWAN

Versa vendorConfig{ } parameters Mandatory Type Example Possible Values Description
localId Yes string SDWAN-Branch@Versa.com   Email address of the branch location. 
remoteId Yes string Controller-01-staging@Versa.com   Email address of the controller side. 
serialNumber Yes string 12345   The customer selects a serial number when setting up the device template on Versa director. Versa post-staging device serial number on Versa director should match this input.
controller1 Yes string 54.219.248.29   Ip address of the SD-WAN controller1. 
controller2 Yes string 54.177.220.115   Ip address of the SD-WAN controller2. 

 

 

If you want to create an HA device that has a secondary device for high availability, please do the following:

      1) set parameters of the optional secondary object

      2) provide two different licenseFileIds for Cisco SDWAN, or two different licenseKeys (ION keys) and licenseSecrets (Secret keys) for CloudGenix in the request body payload

      3) you may have a different set of ACLs, account number, additionalBandwidth, metroCode, and notifications for your secondary device.

     

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

A sample curl request to create a virtual Cisco SDWAN device with NO secondary device (non-HA).

 

curl -X POST 
  https://api.equinix.com/ne/v1/device?draft=false
  -H 'Authorization: Bearer dbFb0zo203fxyRpBrGd6wAX3IGSR' 
  -H 'Content-Type: application/json' 
  -d '
{
    "throughput": 1,
    "throughputUnit": "Gbps",
    "metroCode": "SV",
    "deviceTypeCode": "CSRSDWAN",
    "termLength": "1",
    "licenseMode": "BYOL",
    "packageCode": "ESSENTIALS",
    "virtualDeviceName": "API-SROY-SD101",
    "notifications": [
        "test@equinix.com"
    ],
    "vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "5"},
    "acl": [
        "15.0.0.0/8"
    ],
    "licenseFileId": "abc388de-7e48-4521-9390-f8eb3474b74f",
    "accountNumber": "5710199",
    "additionalBandwidth": "300"
}
'

 

A sample curl request to create an HA virtual Cisco SDWAN device that has a secondary device for high availability (HA). 

 

curl -X POST 
https://api.equinix.com/ne/v1/device?draft=false
-H 'Authorization: Bearer dbFb0zo203fxyRpBrGd6wAX3IGSR' 
-H 'Content-Type: application/json' 

-d '

{

 "throughput": 1,

    "throughputUnit": "Gbps",

    "metroCode": "SV",

    "deviceTypeCode": "CSRSDWAN",

    "termLength": "1",

    "licenseMode": "BYOL",

    "packageCode": "ESSENTIALS",

    "virtualDeviceName": "API SROY-1",

    "notifications": [

        "test@equinix.com"

    ],

    "vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "5"},

    "acl": [

        "15.0.0.0/8"

    ],

    "licenseFileId": "abc388de-7e48-4521-9390-f8eb3474b74f",

    "accountNumber": "5710199",

    "additionalBandwidth": "300",

"secondary":{

"metroCode":"SV",

"notifications":["test@equinix.com"],

"virtualDeviceName":"API SROY-1-sec",

"vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "12345"},

"acl":["10.10.10.1/32"],

"licenseFileId":"abc388de-7e48-4521-9390-f8eb3474b74f",

"accountNumber":"5710199"

}

}

'

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Possible Values Description
draft No boolean False True, False Default=false. To save a draft, set draft=true. You must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode to save a draft. LicenseFileId information will not be saved for drafts. Also, this API will not do access control list validation when you save a draft. 
draftUUID No string ec68e425-f973-452e-a866-76be5844d0ba   To create a device from a draft that you saved earlier, provide the unique Id of the draft (draftUUID). 

 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Possible Values Description
additionalBandwidth   integer 100   Additional bandwidth. You may have a different additional bandwidth for your secondary device in case you have an HA device. You cannot have additionalBandwidth for CloudGenix devices.
deviceTypeCode Yes string CSRSDWAN

CSRSDWAN, CGENIXSDWAN

Virtual device type (device type code). 
licenseFileId   string 6651aef5-e738-411f-8675-5f6b7b9cd429   License file Id. Mandatory for Cisco SDWAN devices. 
licenseMode Yes string BYOL   License type. For now, the only available option is BYOL (bring your own license).
metroCode Yes string SV   Metro code. You may provide two different metros for your HA device. 
notifications Yes array [test@equinix.com]   Email addresses for device life-cycle notification. We need a minimum of 1 and no more than 5 email addresses. You may have a different notification list for your HA device that has a secondary device for high availability. 
packageCode Yes string ESSENTIALS   Software package code. 
termLength Yes integer 24   Billing term length in months. Default = 1 month.
throughput   integer 500   Throughput. Mandatory for Cisco SDWAN. You cannot specify throughput for CloudGenix devices. 
throughputUnit   string Mbps   Throughput unit. Mandatory for Cisco SDWAN. You cannot specify throughputUnit for CloudGenix devices. 
vendorConfig Yes object "vendorConfig": {"systemIpAddress": "1.1.1.1", "siteId": "12345"}   Vendor parameters are vendor-specific. To check the parameters for your vendor device, please check here.
virtualDeviceName Yes string CiscoSTROY   Virtual device name for identification. This should be minimum 3 and maximum 50 characters long. 
acl Yes array[string] ["192.168.10.0/24"]   IP addresses, no more than 50, in CIDR format. For Cisco SDWAN devices, you must provide the IP addresses of vBond, vManage, and vSmart servers, so you can whitelist them on Equinix portal. You may have two distinct sets of ACLs in case you have an HA device with a secondary device for high availability. 
accountNumber   string 10478397

 

Account number. Either an account number or an account referenceId is required to create a virtual device. 
accountReferenceId   string     Account reference Id. This is a temporary ID that can be used to create a device when your account is still pending, not active. Either an account number or an account referenceId is required to create a virtual device. 
purchaseOrderNumber   string 3456789   Purchase order number. Optional field that customers can use to track this device creation to their own purchase order number. 
secondary   object secondary{}   An object containing the optional HA device details to create a secondary device for high availability. 

 

Sample response for a non-HA device.

 

{
    "uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec"
}

 

Sample response for a virtual device with an additional secondary device for high availability.

 

{
    "uuid": "74d8c6b6-3153-4271-9f0e-45bdc7094dec",
    "secondaryUUID": "de5cf79b-3d16-4ccd-841b-3b68ecda2142"
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
uuid string b43ba509-a7d9-4334-8dee-dc4f29bf2e77 Unique identifier of the SDWAN virtual device.
secondaryUUID string 92c2e49d-2c35-432d-a9af-016920bef70c Unique identifier of the secondary SDWAN virtual device (HA).

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 

When an SDWAN device is created, the device transitions through various states within the Equinix infrastructure. These states can be monitored using the "status" response attribute of the Get Virtual Device {UUID} API. Once your device is provisioned and the license is applied, you can create connections to cloud service providers.

 

Virtual device states Description
INITIALIZING Equinix is in the process of reserving resources and creating the device.
PENDING_ACCOUNT Customer's account is not approved. The device creation will continue once the account gets approved.
PROVISIONING Device is booting.
WAITING_FOR_PRIMARY The secondary device is ready but the primary is not. This state might appear only if you have requested a secondary device for high availability (HA). 
WAITING_FOR_SECONDARY The primary device is ready but the secondary is not. This state might appear only if you have requested a secondary device for high availability (HA). 
FAILED Device creation failed. 
PROVISIONED Device is ready. 
DEPROVISIONING Equinix accepted customer's request to delete virtual device. 
DEPROVISIONED Device is deprovisioned/deleted. 

 

 

 

When an end-user deletes a device using the Delete virtual device API,  the device transitions through the following states within the Equinix infrastructure. 

 

status Description
DEPROVISIONING Equinix accepted customer's request to delete virtual device. 
DEPROVISIONED Device is deprovisioned/deleted. 

 


body: 
 
Sample payloads for specific devices

 

Parameter Name Cisco SD-WAN CloudGenix SD-WAN Versa SD-WAN
deviceTypeCode CSRSDWAN CGENIXSDWAN VERSA_SDWAN
licenseMode BYOL BYOL BYOL
licenseFileId cf92ee6f-286f-496e-b4a1-7b4d1802109e    
notifications test@equinix.com test@equinix.com test@equinix.com
metroCode DC DC DC
acl 192.168.1.1/32 192.168.1.1/32 192.168.1.1/32
packageCode ESSENTIALS 3102V FLEX_VNF
throughput 500 500 500
throughputUnit Mbps Mbps Mbps
virtualDeviceName mySDWANSsroy myCGSDWANsroy myVersaSDWANsroy
accountNumber 1234567 1234567 1234567
addtionalBandwidth 100 100 100
purchaseOrderNumber 888888 888888 88888
siteId 456    
systemIpAddress 1.1.1.1    
licenseKey   1404-991d81bb-2567-43e5-a14c-1493ace58046  
licenseSecret   d29dceeef2d2b494c9eb76937a361890786e609d  
termLength 12 12 12
localId     SDWAN-Branch@Versa.com
remoteId     Controller-01-staging@Versa.com
serialNumber     12345
controller1     54.219.248.29
controller2     54.177.220.115

 


body: 

GET price

GET /ne/v1/device/price

 Method  GET
 URL or End Point  /ne/v1/device/price
 Headers  Authorization, Content-Type
 Query Parameters accountNumber, metro, vendorPackage, licenseType, softwarePackage,   throughput, throughputUnit, termLength,  additionalBandwidth,   secondaryAccountNumber, secondaryMetro, secondaryAdditionalBandwidth
 Body  Not applicable

 

This API returns the price of a virtual device based on your selection of metro, vendor package, license type, software package, and throughput. NOTE: the price will not include charges for optional features added to the device, some of which are charged. In case you want a secondary high availability device (HA device), you can use this API to get the prices of both the primary and secondary devices. 

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request and its JSON response. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/price?accountNumber=2252619&metro=DC&vendorPackage=CSR1000V&licenseType=SUB&softwarePackage=IPBASE&throughput=500&throughputUnit=Mbps&termLength=24&additionalBandwidth=100&secondaryAccountNumber=708979&secondaryMetro=DC&secondaryAdditionalBandwidth=200"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
accountNumber Yes integer 2252726   Account number. As this account gets charged, it must be in the metro where you want the device.
metro Yes string DC   Metro where you want the device.
vendorPackage Yes string CSR1000V   Vendor package (device type code).
licenseType   string SUB  

License type, whether you want a subscription license (Equinix handles the license and charges monthly) or you want to bring your own license (BYOL).

softwarePackage Yes string IPBASE   Software package code.
throughput Yes string 500   Throughput.
throughputUnit Yes string Mbps   Throughput Unit.
termLength   string 1   The term length of the contract in months. Default = 1 month.
additionalBandwidth   integer 100   Additional bandwidth (in Mbps).
secondaryAccountNumber   integer 2242345   Secondary account number for high availability (HA) device. You must provide a secondary account number to get the price of your secondary device.
secondaryMetro   string DC   Secondary metro for high availability (HA) device. You must provide a second metro location to get the price of your secondary device. 
secondaryAdditionalBandwidth   integer 100   Secondary additional bandwidth for high availability (HA) device in Mbps.

 

Sample response:

 

{
    "termLength": "12",
    "primary": {
        "charges": [
            {
                "description": "VIRTUAL_DEVICE",
                "monthlyRecurringCharges": "423.20"
            },
            {
                "description": "DEVICE_LICENSE",
                "monthlyRecurringCharges": "0.00"
            },
            {
                "description": "ADDITIONAL_BANDWIDTH",
                "monthlyRecurringCharges": "1932.00"
            }
        ],
        "currency": "USD"
    },
    "secondary": {
        "charges": [
            {
                "description": "VIRTUAL_DEVICE",
                "monthlyRecurringCharges": "423.20"
            },
            {
                "description": "DEVICE_LICENSE",
                "monthlyRecurringCharges": "0.00"
            },
            {
                "description": "ADDITIONAL_BANDWIDTH",
                "monthlyRecurringCharges": "1288.00"
            }
        ],
        "currency": "USD"
    }
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
termLength string 1 The term length of the contract. 
primary object primary{} Price details of the primary device.
charges array charges[] Array of charges.
description string VIRTUAL_DEVICE Description of the charge, whether it is for a virtual device, device license, or additional bandwidth. 
monthlyRecurringCharges string 566 Monthly charges.
currency string USD Currency.
secondary object secondary{} Price details of the secondary object, in case you want a secondary object for high availability.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET virtual device interfaces {UUID}

GET /ne/v1/device/{uuid}/interfaces

 Method  GET
 URL or End Point  /ne/v1/device/{uuid}/interfaces
 Headers  Authorization, Content-Type
 Path Parameter  UUID
 Body  Not applicable

 

Call this API to find out the status of virtual device interfaces.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

A sample curl request: 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/ec68e425-f973-452e-a866-76be5844d0ba/interfaces"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Path Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string ec68e425-f973-452e-a866-76be5844d0ba   Unique ID of the virtual device. 

 

Sample response: 

 

[
    {
        "id": 1,
        "name": "GigabitEthernet1",
        "status": null,
        "operationalStatus": null,
        "macAddress": null,
        "ipAddress": null,
        "assignedType": "Equinix Managed"
    },
    {
        "id": 2,
        "name": "GigabitEthernet2",
        "status": null,
        "operationalStatus": null,
        "macAddress": null,
        "ipAddress": null,
        "assignedType": "Equinix Managed"
    },
    {
        "id": 3,
        "name": "GigabitEthernet3",
        "status": "RESERVED",
        "operationalStatus": "down",
        "macAddress": "fa16.3e1b.4217",
        "ipAddress": null,
        "assignedType": "Connection to Network Service Provider"
    },
    {
        "id": 4,
        "name": "GigabitEthernet4",
        "status": "AVAILABLE",
        "operationalStatus": "down",
        "macAddress": "fa16.3e41.415d",
        "ipAddress": null,
        "assignedType": ""
    },
    {
        "id": 5,
        "name": "GigabitEthernet5",
        "status": "AVAILABLE",
        "operationalStatus": "down",
        "macAddress": "fa16.3e32.daef",
        "ipAddress": null,
        "assignedType": ""
    },
    {
        "id": 6,
        "name": "GigabitEthernet6",
        "status": "AVAILABLE",
        "operationalStatus": "down",
        "macAddress": "fa16.3e99.2759",
        "ipAddress": null,
        "assignedType": ""
    },
    {
        "id": 7,
        "name": "GigabitEthernet7",
        "status": "AVAILABLE",
        "operationalStatus": "down",
        "macAddress": "fa16.3e84.74fb",
        "ipAddress": null,
        "assignedType": ""
    },
    {
        "id": 8,
        "name": "GigabitEthernet8",
        "status": "AVAILABLE",
        "operationalStatus": "down",
        "macAddress": "fa16.3e9c.e83c",
        "ipAddress": null,
        "assignedType": ""
    },
    {
        "id": 9,
        "name": "GigabitEthernet9",
        "status": "AVAILABLE",
        "operationalStatus": "down",
        "macAddress": "fa16.3efb.ec61",
        "ipAddress": null,
        "assignedType": ""
    },
    {
        "id": 10,
        "name": "GigabitEthernet10",
        "status": "AVAILABLE",
        "operationalStatus": "down",
        "macAddress": "fa16.3ebf.3d29",
        "ipAddress": null,
        "assignedType": ""
    }
]

 

 

The description of the response is as follows:

 

Field Name Type Example Values Possible Values Description
id string 10   Id of the interface.
name string ethernet1/9   Name of the interface.
status string AVAILABLE AVAILABLE, ASSIGNED, RESERVED Assigned interfaces are already in use. Reserved interfaces can only be used to bring your own connection (BYOC) from your Network Service Providers. 
operationalStatus string down up, down Operational status of the interface, whether it is up or down.
macAddress string fa:16:3e:5f:41:06   Media access control address. 
ipAddress string     Ip address.
assignedType string test(AWS Direct Connect)   This field has the connection name and the service profile of the connection in brackets.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 
Associate a device to an SSH user

PATCH /ne/v1/services/ssh-user/{UUID}/association

 Method  PATCH
 URL or End Point  /ne/v1/services/ssh-user/{uuid}/association
 Headers  Authorization, Content-Type
 Query Parameters  deviceUuid
 Path Parameters  uuid

 

Call this API to associate a device to an SSH user.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request:

 

curl -X

PATCH "https://api.equinix.com/ne/v1/services/ssh-user/fa02d9df-75c2-4763-b9f7-89a06bf6376a/association?deviceUuid=afeb071c-227b-4be2-8fd5-ced81fd37273"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
 

 

 

The description of the query parameter is as follows:

 

Query Parameter Name Mandatory Type Example Possible Values Description
deviceUuid Yes string afeb071c-227b-4be2-8fd5-ced81fd37273   Unique Id of the device.

 

The description of the path parameter is as follows:

 

Path Parameter Name Mandatory Type Example Possible Values Description
uuid Yes string ec68e425-f973-452e-a866-76be5844d0ba   The unique Id of the ssh user.

 

Sample response:

 

201

 

The description of the response payload is as follows:

 

HTTP status Description
201 Association created successfully.

 


body: 
Update a virtual device

PATCH /ne/v1/device/{UUID}

 Method  PATCH
 URL or End Point  /ne/v1/device/{uuid}
 Headers  Authorization, Content-Type
 Path Parameters  uuid
 Body Parameters

 notifications[...], virtualDeviceName

 

Call this API to update a virtual device name and the list of emails to be notified. 

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request to update a device.

 

curl -X

PATCH "https://api.equinix.com/ne/v1/device/fa02d9df-75c2-4763-b9f7-89a06bf6376a"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{
  "notifications": [
    "test1@example.com"
  ],
  "virtualDeviceName": "Router1-csr1000v"
}'

 

The description of the path parameter is as follows:

 

Path Parameter Name Mandatory Type Example Possible Values Description
uuid Yes string ec68e425-f973-452e-a866-76be5844d0ba   The unique Id of the device. 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Possible Values Description
notifications No array [test1@example.com]   Email addresses for device life-cycle notifications. Equinix needs a minimum of 1 and no more than 5 email addresses. You may have a different notification list for your HA device that has a secondary device for high availability. 
virtualDeviceName No string CiscoSTROY   Virtual device name for identification. This should be minimum 3 and maximum 50 characters long. 

 

Sample response for a non-HA device.

 

204

 

Response payload:

 

HTTP status Description
204 Request accepted.

 

 


body: 

GET order summary

GET /ne/v1/device/order-summary

 Method  GET
 URL or End Point  /ne/v1/device/order-summary
 Headers  Authorization, Content-Type
 Query Parameters  accountNumber, metro, vendorPackage, licenseType, softwarePackage,   throughput, throughputUnit, termLength,  additionalBandwidth,   secondaryAccountNumber, secondaryMetro, secondaryAdditionalBandwidth
 Body  Not applicable

 

Gets the Equinix order summary as a printable pdf file. This API helps customers who need an order estimate to go through a PO process at their end to make a purchase. 

 

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

 

A sample curl request: 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/order-summary?accountNumber=2252619&metro=DC&vendorPackage=CSR1000V&licenseType=SUB&softwarePackage=IPBASE&throughput=500&throughputUnit=Mbps&termLength=24&additionalBandwidth=100"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
accountNumber Yes integer 2252726   Account number. As this account gets charged, it must be in the metro where you want the device.
metro Yes string DC   Metro where you want the device.
vendorPackage Yes string CSR1000V   Vendor package (device type code).
licenseType   string SUB  

License type, whether you want a subscription license (Equinix handles the license and charges monthly) or you want to bring your own license (BYOL).

softwarePackage Yes string IPBASE   Software package code.
throughput Yes string 500   Throughput of the device.
throughputUnit Yes string Mbps   Throughput Unit.
termLength   string 1   The term length of the contract in months.
additionalBandwidth   integer 100   Additional bandwidth (in Mbps).
secondaryAccountNumber   integer 2242345   Secondary account number for high availability (HA) device.
secondaryMetro   string DC   Secondary metro for high availability (HA) device..
secondaryAdditionalBandwidth   integer 100   Secondary additional bandwidth for high availability (HA) device in Mbps.

 

Sample response:

 

200 Okay

 

The description of the response header is as follows:

 

Parameter Description
Content-Type application/pdf;charset=UTF-8. The response is a pdf file that you can save or view online. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET order terms 

GET ne/v1/device/agreement/order

 Method  GET
 URL or End Point  ne/v1/device/agreement/order
 Headers  Authorization, Content-Type
 Path Parameter  Not applicable
 Body  Not applicable

 

Call this API to find out the order and vendor-specific terms and conditions. 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

A sample curl request. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/agreement/order"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Sample response:

 

{
    "terms": "By clicking \"Accept\" you are agreeing to the terms and conditions of this Order on behalf of your Company. You are acknowledging that you have the full authority on behalf of your Company to enter into this online Order (\"Order\") as governed by and incorporated by reference into the applicable Master Country Agreement, Interconnection Terms and Conditions, or other similar agreement agreed to between the Parties (\"Agreement\").\r\n\r\nUnless otherwise defined in this Order or if the context requires otherwise, all capitalized terms used in this Order shall have the meanings ascribed to them in the Agreement.\r\n‘Product(s)’ as used in this Order means all the products under this Order, including Licensed Space and/or Services (if any).\r\n\r\nThe Initial Term is the term stated above, which commence on the date the Product(s) are delivered (“Effective Date”).  \r\n\r\nAfter the Initial Term, the term will automatically renew for a period equal to the Initial Term unless either Party terminates this Order by providing written non-renewal notice 90 days prior to the end of the then-current term to the other Party in which event this Order will terminate at the end of the then-current term. For the avoidance of doubt, the notice period for an Initial Term of one month is 30 days, rather than 90 days. \r\n\r\n\r\nThis Order incorporates the Product Provider EULA provided by Equinix to the Customer in Attachment A of this Order and the Product Policies, which are attached as Exhibits to the Customer’s Interconnection Terms and Conditions. All Product(s) selected as part of this Order are subject to availability.\r\n\r\nEquinix, in its sole discretion, reserves the right to reject any handwritten or typed modification to this Agreement or any Order which is not mutually agreed to in writing. \r\n\r\nFor purposes of this Order, the Parties hereby agree that the following ‘Price Increase Terms’ grid is not applicable to the Network Edge Service and is of no force or effect.\r\n\r\nIf you have any questions regarding the terms of this Order, please contact your Equinix Sales Representative.\r\n\r\n\r\n \r\nATTACHMENT A \r\nPRODUCT PROVIDER EULA"
}

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
terms string By clicking "Accept" you are agreeing to the terms and conditions of this Order on behalf of your Company. You are acknowledging that you have the full authority on behalf of your Company to enter into this online Order "Order" as governed by and incorporated by reference into the applicable Master Country Agreement, Interconnection Terms and Conditions, or other similar agreement agreed to between the Parties "Agreement." Unless otherwise defined in this Order or if the context requires otherwise, all capitalized terms used in this Order shall have the meanings ascribed to them in the Agreement.‘Product(s)’ as used in this Order means all the products under this Order, including Licensed Space and/or Services (if any). The Initial Term is the term stated above, which commence on the date the Product(s) are delivered (“Effective Date”). After the Initial Term, the term will automatically renew for a period equal to the Initial Term unless either Party terminates this Order by providing written non-renewal notice 90 days prior to the end of the then-current term to the other Party in which event this Order will terminate at the end of the then-current term. For avoidance of doubt, the notice period for an Initial Term of one month is 30 days, rather than 90 days. This Order incorporates the Product Provider EULA provided by Equinix to the Customer in Attachment A of this Order and the Product Policies, which are attached as Exhibits to the Customer’s Interconnection Terms and Conditions. All Product(s) selected as part of this Order are subject to availability. Equinix, in its sole discretion, reserves the right to reject any handwritten or typed modification to this Agreement or any Order which is not mutually agreed to in writing. For purposes of this Order, the Parties hereby agree that the following ‘Price Increase Terms’ grid is not applicable to the Network Edge Service and is of no force or effect. If you have any questions regarding the terms of this Order, please contact your Equinix Sales Representative. A PRODUCT PROVIDER EULABy clicking \"Accept\" you are agreeing to the terms and conditions of this Order on behalf of your Company. You are acknowledging that you have the full authority on behalf of your Company to enter into this online Order (\"Order\") as governed by and incorporated by reference into the applicable Master Country Agreement, Interconnection Terms and Conditions, or other similar agreement agreed to between the Parties (\"Agreement\"). Unless otherwise defined in this Order or if the context requires otherwise, all capitalized terms used in this Order shall have the meanings ascribed to them in the Agreement.\r\n‘Product(s)’ as used in this Order means all the products under this Order, including Licensed Space and/or Services (if any). The Initial Term is the term stated above, which commence on the date the Product(s) are delivered (“Effective Date”).  \r\n\r\nAfter the Initial Term, the term will automatically renew for a period equal to the Initial Term unless either Party terminates this Order by providing written non-renewal notice 90 days prior to the end of the then-current term to the other Party in which event this Order will terminate at the end of the then-current term. For the avoidance of doubt, the notice period for an Initial Term of one month is 30 days, rather than 90 days. \r\n\r\n\r\nThis Order incorporates the Product Provider EULA provided by Equinix to the Customer in Attachment A of this Order and the Product Policies, which are attached as Exhibits to the Customer’s Interconnection Terms and Conditions  . All Product(s) selected as part of this Order are subject to availability.\r\n\r\nEquinix, in its sole discretion, reserves the right to reject any handwritten or typed modification to this Agreement or any Order which is not mutually agreed to in writing. For purposes of this Order, the Parties hereby agree that the following ‘Price Increase Terms’ grid is not applicable to the Network Edge Service and is of no force or effect. If you have any questions regarding the terms of this Order, please contact your Equinix Sales Representative. ATTACHMENT A PRODUCT PROVIDER EULA Equinix order terms and conditions.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET vendor terms

GET ne/v1/device/agreement/vendor

 Method  GET
 URL or End Point  ne/v1/device/agreement/vendor
 Headers  Authorization, Content-Type
 Query Parameters  vendorPackage, licenseType
 Body  Not applicable

 

Call this API to get a link to your vendor's terms. 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/agreement/vendor?vendorPackage=CSR1000V&licenseType=SUB"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the request parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
vendorPackage Yes string

CSR1000V

 

Vendor package. This code specifies the device type (firewall, router, or SDWAN device) you want. 
licenseType Yes string SUB SUB, BYOL License type, whether subscription (SUB) or bring your own license (BYOL). 

 

Sample response:

 

{
  "terms": "https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html"
}

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
terms string

https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html

A link to the vendor terms. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

PUT additional bandwidth

PUT /ne/v1/device/additionalbandwidth/{virtualDeviceUUID}

 Method  PUT
 URL or End Point  /ne/v1/device/additionalbandwidth/{virtualDeviceUUID}
 Headers  Authorization, Content-Type
 Path Parameter  virtualDeviceUUID
 Body Parameter  additionalBandwidth

 

Call this API to update/add additional bandwidth to an existing virtual device that is registered and provisioned. You must have set up an ACL (access control) list before you can add additional bandwidth to a device. 

 

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

 

curl -X

PUT "https://api.equinix.com/ne/v1/device/additionalbandwidth/f61e75d2-2008-43f4-bfee-1dd17b1e1a28"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d "{
"additionalBandwidth": 200

}"

 

The description of the path parameter is as follows:

 

Path Parameter Name Mandatory Type Example Applicable Values Description
virtualDeviceUUID Yes string f61e75d2-2008-43f4-bfee-1dd17b1e1a28

 

Unique Id of the virtual device.

 

The description of the body is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
additionalBandwidth Yes integer 200

 

Additional bandwidth. 

 

204 No Content

 

The description of the response payload is as follows:

 

HTTP status Description
204 No Content The request was successfully processed.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 
Update a draft device

PUT /ne/v1/device/{UUID}

 Method  PUT
 URL or End Point  /ne/v1/device/{uuid}
 Headers  Authorization, Content-Type
 Query Parameters  draft
 Path Parameters  uuid
 Body Parameters

 additionalBandwidth, deviceTypeCode, hostNamePrefix, licenseFileId, licenseKey, licenseMode, licenseSecret, licenseToken, metroCode, 

 notifications[...], packageCode, siteId, sshUsers[sshUserUuid, action, sshUsername, sshPassword], systemIpAddress, termLength,

 throughput, throughputUnit, virtualDeviceName,   acl[...], accountNumber, accountReferenceId, 

 purchaseOrderNumber, secondary   {accountNumber, accountReferenceId, acl[...], additionalBandwidth, licenseFileId, licenseKey, licenseSecret,

 licenseToken, metroCode, notifications[...], siteId, 

 sshUsers[{sshUserUuid, action, sshUsername, sshPassword}], systemIpAddress, virtualDeviceName"}

 

Call this API to update a draft device. 

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request to update a draft with NO secondary device (non-HA).

 

curl -X

PUT "https://api.equinix.com/ne/v1/device/fa02d9df-75c2-4763-b9f7-89a06bf6376a?draft=true"
-H "content-type: application/json"
-H "Authorization: Bearer jnSoUKaJHpzMnU0toROpUHmqnwEP"
-d '{
  "additionalBandwidth": 100,
  "deviceTypeCode": "CSR1000V",
  "hostNamePrefix": "myhostSR",
  "licenseFileId": "d6e21e0c-86dd-11e8-adc0-fa7ae01bbebc",
  "licenseMode": "BYOL",
  "metroCode": "DC",
  "notifications": [
    "test1@example.com"
  ],
  "packageCode": "IPBASE",
  "sshUsers": [
    {
      "sshUserUuid": "",
      "action": "CREATE",
      "sshUsername": "cust0001_DC",
      "sshPassword": "projPass"
    }
  ],
  "termLength": 1,
  "throughput": 500,
  "throughputUnit": "Mbps",
  "virtualDeviceName": "Router1-csr1000v",
  "acl": [
    "192.168.1.1/29"
  ],
  "accountNumber": "708979",
  "purchaseOrderNumber": "123456"
}'

 

 

The description of the query parameter is as follows:

 

Query Parameter Name Mandatory Type Example Possible Values Description
draft Yes boolean True True To save a draft, set draft=true. As of now, this API does not support draft=false. You cannot create/update a device using this API. You must provide deviceTypeCode, accountNumber/accountReferenceId, and metroCode to save a draft. sshUsers and licenseFileId information will not be saved for drafts. Also, this API will not do access control list validation when you save a draft. 

 

The description of the path parameter is as follows:

 

Path Parameter Name Mandatory Type Example Possible Values Description
uuid Yes string ec68e425-f973-452e-a866-76be5844d0ba   The unique Id of the draft (draftUUID). 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Possible Values Description
additionalBandwidth No integer 100   Addtional bandwidth. You may have a different additional bandwidth for your secondary device in case you have a secondary device for high availability.
deviceTypeCode Yes string CSR1000V

 

Virtual device type (device type code).
hostNamePrefix No string mySE   Host name prefix. This gets included as part of an FQDN that ensures that the device is reachable from approved sources, if desired. Only a-z, A-Z, 0-9 and hyphen(-) are allowed. It should start with a letter and end with a letter or a digit. Also, it should be minimum 2 and maximum 10 characters long. 
licenseFileID No string 6651aef5-e738-411f-8675-5f6b7b9cd429   License file Id is mandatory for some vendors-devices. If you select subscription license model (SUB), then you do not need to provide a licenseFileId. For Cisco HA devices, you must upload two different license files. For Juniper HA devices, you may use the same license file for both the devices. 
licenseKey No string 6735-vwe64568-6a91-4112-8734-bea12d91f7y7   License key (primarily for CloudGenix SDWAN devices).
licenseMode No string BYOL BYOL, SUB License type. One of SUB (subscription) or BYOL (bring your own license) from your vendor. 
licenseSecret No string h5j0i45e83324pblbfca764532c4a640e7801f0   License secret (primarily for CloudGenix SDWAN devices).
licenseToken No string V74191621   License token is mandatory for some vendor-devices that provide/accept a license token. You do not need to provide a license token if you want a subscription model or if your vendor provides license files. This field must have 8 alphanumeric characters. 
metroCode Yes string  SV   Metro code. You do not need to provide two different metros for your HA device that has a secondary device for high availability, but you may if you want to.
notifications No array [test1@example.com]   Email addresses for notification. We need a minimum of 1 and no more than 5 email addresses. You may have a different notification list for your HA device that has a secondary device for high availability. 
packageCode No string VM100   Software package code.
siteId No string     Site Id. A siteId is a particular physical location within the Viptela overlay network, such as a branch office or a campus.
sshUsers No array[object] [{
        "sshUserUuid": "",
        "action": "CREATE",
        "sshUsername": "cust00011_DCT",
        "sshPassword": "projPass!"
      }]
  SSH users. You may have two distinct sets of ssh users in case you have an HA device with a secondary device for high availability. 
sshUserUuid No string ef673cd4-9fc2-4ab4-810e-7274aaf7bc2d   Required for DELETE, REUSE operations. In case you want to REUSE an existing user, please provide the unique Id of the user. 
action No string CREATE CREATE, DELETE, REUSE Action to be performed, whether you want to create a new user, delete a user, or reuse a user. 
sshUsername No string cust00011_DCT   SSH username.
sshPassword No string projPass!   SSH user password. 
systemIpAddress No string 192.168.1.5   System Ip Address. Mandatory for Cisco SDWAN devices. Each vEdge router and vSmart controller is assigned a system IP address. It should be in decimal four-part dotted notation, just like IPv4 address. 
termLength No integer 12   Billing term length in months.
throughput No integer 500   Throughput of the device.
throughputUnit No string Mbps   Throughput unit.
virtualDeviceName No string CiscoSTROY   Virtual device name for identification. This should be minimum 3 and maximum 50 characters long. 
acl No array[string] ["192.168.10.0/24"]   IP addresses, no more than 50, in CIDR format. You may have two distinct sets of ACLs in case you have an HA device with a secondary device for high availability.  
accountNumber No string 10478397

 

Account number. Either an account number or an account referenceId is required to create a draft device. 
accountReferenceId No string 791281   Account reference Id. This is a temporary ID that can be used to create a draft device when your account is still pending, not active. Either an account number or an account referenceId is required to create a draft device. 
purchaseOrderNumber No string 3456789   Purchase order number. Optional field that customers can use to track this device creation to their own purchase order number. 
secondary No object secondary{}   Object containing the optional HA device details to create a secondary device for high availability. 

 

Sample response for a non-HA device.

 

204

 

The description of the response payload is as follows:

 

HTTP status Description
204 Request accepted.

 

 

You can query the details of a draft by making a GET call to the API /ne/v1/device/{uuid}. You can delete a draft by making a DEL call to the API /ne/v1/device/{uuid}

 


body: 

GET metro

GET /ne/v1/device/metro

 Method  GET
 URL or End Point  /ne/v1/device/metro
 Headers  Authorization, Content-Type
 Query Parameters  region, page, size
 Body Parameters  Not applicable

 

The Get metro API returns all available metros where the NE platform is available. 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 its JSON response. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/metro"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Response:

{
    "totalCount": 2,
    "pageNumber": 1,
    "pageSize": 20,
    "content": [
        {
            "region": "AMER",
            "metroCode": "DC",
            "metroDescription": "Ashburn"
        },
        {
            "region": "EMEA",
            "metroCode": "LD",
            "metroDescription": "London"
        }
    ]
}

 

The description of the request parameters is as follows:

 

Field name Mandatory Type Example Applicable Values Description
region No string

AMER

AMER,

EMEA,

APAC

The geographic region code where the metro resides. Three possible regions are “AMER”, “EMEA or “APAC”.
page No integer 1   Page number.
size No integer

20

  Results per page.

 

 

The description of the response payload is as follows:

 

Field name Type Example Description
totalCount string 2 The number of items returned.
pageNumber integer 1 Page number.
pageSize integer 20 The number of items displayed per page. 
content array   An array containing the metro objects.
region string

AMER

EMEA

APAC

The geographic region code where the metro resides. Three possible regions are “AMER”, “EMEA or “APAC”.
metroCode string DC The two-character code used to denote the metro.
metroDescription string

London

The name of the metro.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET device types

GET /ne/v1/device/type

 Method  GET
 URL or End Point  /ne/v1/device/type
 Headers  Authorization, Content-Type
 Query Parameters  deviceTypeCode, category, page, size
 Body  Not applicable

 

Call this API to find out which virtual device (e.g., router or firewall) you want to launch on the NE platform. You will learn about the metro regions where virtual devices are available, vendors of devices, available software packages, and all possible licensing and throughput options. 

 

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

 

The following screenshots show a sample curl request and its respective JSON response. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/type"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Query Parameter Name Mandatory Type Example Applicable Values Description
deviceTypeCode No string CSR1000V   Code of the device you want.
category No string ROUTER

"ROUTER",

"FIREWALL",

"SDWAN"

Type of device you want.
page No string 1   Page number. Default value=1.
size No string 100   Results per page. Default value=100.

 

Sample response:

 

{
    "totalCount": 1,
    "pageNumber": 1,
    "pageSize": 100,
    "content": [
       {
            "deviceTypeCode": "CSR1000V",
            "name": "CSR 1000V",
            "description": "The [Cisco CSR 1000v Router Series|https://www.cisco.com/c/en/us/products/routers/cloud-services-router-1000v-series/index.html] serves as a secure single-tenant router in a multi-tenant, shared-resource public cloud environment. It provides end-to-end managed connectivity, enabling the user to construct a secure network connection and seamlessly extend it to public and virtual private clouds. Deploy a complete, hypervisor-isolated, multiservice secure instance for each tenant. Secure features include IPsec VPNs and built-in zone-based firewalls, among others.",
            "vendor": "Cisco",
            "category": "ROUTER",
            "licenseOptions": [
                {
                    "type": "Sub",
                    "name": "Subscription"
                },
                {
                    "type": "BYOL",
                    "name": "Bring Your Own License"
                }
            ],
            "throughputOptions": [
                {
                    "metroCodes": [
                        "LD",
                        "DC",
                        "SV"
                    ],
                    "throughput": 500,
                    "throughputUnit": "Mbps"
                },
                {
                    "metroCodes": [
                        "LD",
                        "DC",
                        "SV"
                    ],
                    "throughput": 1,
                    "throughputUnit": "Gbps"
                },
                {
                    "metroCodes": [
                        "SV"
                    ],
                    "throughput": 10,
                    "throughputUnit": "Gbps"
                }
            ],
            "availableMetros": [
                {
                    "metroCode": "LD",
                    "metroDescription": "London",
                    "region": "EMEA"
                },
                {
                    "metroCode": "DC",
                    "metroDescription": "Ashburn",
                    "region": "AMER"
                },
                {
                    "metroCode": "SV",
                    "metroDescription": "Silicon Valley",
                    "region": "AMER"
                }
            ],
            "softwarePackages": [
                {
                    "packageCode": "IPBASE",
                    "name": "IP Base"
                },
                {
                    "packageCode": "SEC",
                    "name": "Security"
                }
            ]
        }
    ]
}

 

The description of the response payload is as follows:

 

Field Name Type Example Values Description
totalCount integer 1 The total count of items returned.
pageNumber integer 1 Page number. 
pageSize integer 20 The number of items displayed per page. 
content array   An array containing the device type objects.
deviceTypeCode string CSR1000V Device type code.
name string CSR 1000V Name of device.
description string The [Cisco CSR 1000v Router Series|https://www.cisco.com/c/en/us/products/routers/cloud-services-router-1000v-series/index.html] serves as a secure single-tenant router in a multi-tenant, shared-resource public cloud environment. It provides end-to-end managed connectivity, enabling the user to construct a secure network connection and seamlessly extend it to public and virtual private clouds. Deploy a complete, hypervisor-isolated, multiservice secure instance for each tenant. Secure features include IPsec VPNs and built-in zone-based firewalls, among others. Device description.
vendor string Cisco Vendor of device.
category string ROUTER Type of virtual device, whether ROUTER or FIREWALL.
licenseOptions array licenseOptions[] An array of available license options, subscription (Sub) or bring your own license (BYOL).
type string BYOL Type of license, either BYOL (bring your own license) or SUB (subscription).
name string Bring Your Own License Name of license, either Bring Your Own License or Subscription. 
throughputOptions array throughputOptions[] An array containing the available throughput options.
throughput string 1 Throughput of the device.
throughputUnit string Gbps Throughput unit.
availableMetros array availableMetros[] An array containing the metros where the device is available.
metroCode string DC Metro code.
metroDescription string Ashburn Metro description.
region string AMER Region in which the metro is located.
softwarePackages array softwarePackages[] An array of available software packages.
packageCode string SEC Code-name of software.
name string Security Name of software.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

GET account {metro} 

GET ne/v1/device/account/{metro}

 Method  GET
 URL or End Point  ne/v1/device/account/{metro}
 Headers  Authorization, Content-Type
 Path Parameters  metro
 Body  Not applicable

 

Call this API to check your account status in the metro where you want a virtual device. To create a virtual device, you must have an account in the metro where you want the virtual device, either in the Active or Pending state. To create an account go to “accountcreateurl.”

 

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 screenshot shows a sample curl request. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/account/SV"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the request parameters is as follows:

 

Path Parameter Name Mandatory Type Example Applicable Values Description
metro Yes string

SV

 

The two-character metro code.

 

Sample response:

 

{
    "accountCreateUrl": "https://dev-nfv.corp.equinix.com/account?referenceId=79160&ibx=SV6&metro=SV&callbackId=a6cd9158-6280-4864-b57e-79b46a128568",
    "accounts": [
        {
            "accountName": "FACEBOOK INC",
            "accountNumber": "110249",
            "accountUcmId": "1000014389",
            "accountStatus": "Active"
        },
        {
            "accountName": "REG2-acc1",
            "accountNumber": "2201097",
            "accountUcmId": "1000014389",
            "accountStatus": "Active"
        },
        {
            "accountName": "FACEBOOK INC",
            "accountNumber": "133911",
            "accountUcmId": "1000008582",
            "accountStatus": "Active"
        },
        {
            "accountName": "Facebook, Inc.",
            "accountNumber": "350603",
            "accountUcmId": "1000675853",
            "accountStatus": "Active"
        },
        {
            "accountName": "Facebook, Inc.",
            "accountNumber": "4257",
            "accountUcmId": "1000007224",
            "accountStatus": "Active"
        },
        {
            "accountName": "TestXXX02",
            "accountStatus": "PROCESSING",
            "referenceId": "791281"
        },
        {
            "accountName": "TestSameAsHqAddress",
            "accountNumber": "",
            "accountStatus": "PROCESSING",
            "referenceId": "762452"
        },
        {
            "accountName": "TestAccountXXX01",
            "accountNumber": "",
            "accountStatus": "PROCESSING",
            "referenceId": "783903"
        },
        {
            "accountName": "Test-xxxxx022",
            "accountUcmId": "24234234-2348-SUDF",
            "accountStatus": "PROCESSING",
            "referenceId": "949134"
        },
        {
            "accountName": "Test-xxxxx028",
            "accountNumber": "",
            "accountStatus": "SUBMITTED",
            "referenceId": "258089"
        },
        {
            "accountName": "TestAc02Oct08",
            "accountNumber": "",
            "accountStatus": "PROCESSING",
            "referenceId": "871892"
        },
        {
            "accountName": "TestAc01Oct08",
            "accountNumber": "",
            "accountStatus": "PROCESSING",
            "referenceId": "320082"
        },
        {
            "accountName": "TESTACC01OCT08",
            "accountStatus": "PROCESSING",
            "referenceId": "636589"
        },
        {
            "accountName": "TestAc01Oct08",
            "accountNumber": "",
            "accountStatus": "PROCESSING",
            "referenceId": "324092"
        },
        {
            "accountName": "TESTACC02OCT08",
            "accountStatus": "PROCESSING",
            "referenceId": "883018"
        },
        {
            "accountName": "TestXXX01",
            "accountStatus": "PROCESSING",
            "referenceId": "189798"
        },
        {
            "accountName": "TestAccount -XXX025",
            "accountStatus": "PROCESSING",
            "referenceId": "921696"
        },
        {
            "accountName": "Reseller Org",
            "accountNumber": "1352619",
            "accountUcmId": "3367D27E-1899-41a5-8AB6-0AC551FF4C01",
            "accountStatus": "Active"
        },
        {
            "accountName": "Subaccount Org",
            "accountNumber": "3472619",
            "accountUcmId": "62C928C4-CD82-4f66-9B5E-C59AF317F61D",
            "accountStatus": "Active"
        }
    ],
    "errorMessage": null,
    "errorCode": null
}

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
accountCreateURL string

https://ecxfabric.equinix.com/account?referenceId=459019&ibx=SV5&metro=SV&callbackId=062bcc1c-e319-42be-9674-200f19b6c3b4

URL to create account. The account create URL will not be there if you have an account.
accounts array accounts[] An array of accounts.
accountName string

TRYKE INC

Account name.
accountNumber string 110249 Account number.
accountUcmId string 1000014389 Unique Id of an account. 
accountStatus string Active Account status. Possible values: Active, Processing.
referenceID string 921696 This is a temporary ID that can be used to create a device when the account is Pending.
subCustomerAccounts array subCustomerAccounts[] An array of subCustomerAccounts associated with a reseller. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

POST a license file before creating a virtual device (BYOL)

POST /ne/v1/device/license/file

 Method  POST
 URL or End Point  /ne/v1/device/license/file
 Headers  Authorization, Content-Type
 Query Parameter  metroCode, deviceTypeCode, licenseType
 Form Data  file

 

In case you want to bring your own license, you can use this API to post a license file that your vendor has provided. This API is for Juniper devices and others that require you to post a license before you create a virtual device. In the API response, you will get a fileID that you can later use to create a virtual device. 

 

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 its JSON response. 

 

POST "https://api.equinix.com/ne/v1/device/license/file?metroCode=SV&deviceTypeCode=CSRSDWAN&licenseType=BYOL"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-H "content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
-F "file=@C:\Users\sroy\Desktop\Documents-equinix\CSR-FA819DC1-96FE-497A-89B4-FE3C897C981F.cfg"

 

The description of the request parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
metroCode Yes string SV

 

Metro code. Metro location for which you want to post a license file.
deviceTypeCode Yes string CSRSDWAN   Device type code. Find deviceTypeCode by calling Get device types API. 
licenseType Yes string BYOL BYOL License type. Use this API to upload a file if you are going to BYOL (bring your own license).

 

 

Form Parameter Name Mandatory Type Example Applicable Values Description
formData Yes file CSR-FA819DC1-96FE-497A-89B4-FE3C897C981F.cfg   License file that your vendor has provided.
 

 

{
    "fileId": "e0578172-7461-458f-91db-634f865fcaf5"
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
fileId string e0578172-7461-458f-91db-634f865fcaf5 File Id. You can use this ID to create a virtual device.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

POST a license file after creating a virtual device

POST /ne/v1/device/license/file/{uuid}

 Method  POST
 URL or End Point  /ne/v1/device/license/file/{uuid}
 Headers  Authorization, Content-Type
 Path Parameter  UUID
 Form Data  file

 

In case you want to bring your own license, you can use this API to post a license file that your vendor has provided. This API is useful in those scenarios (e.g. for Cisco devices) when you create a virtual device first and attach a license to it later. You can also use this API to update a license that is about to expire. 

 

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

 

curl -X

POST "https://api.equinix.com/ne/v1/device/license/file/299ad92a-70ed-4410-91b1-bb99dbb7b9ad"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-H "content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" 
-F "file=@C:\Users\sroy\Desktop\Documents-equinix\licenseFile.lic"

 

The description of the request parameters is as follows:

 

Path Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string ef673cd4-9fc2-4ab4-810e-7274aaf7bc2d

 

Unique ID of virtual device.

 

Form Parameter Name Mandatory Type Example Applicable Values Description
formData Yes file sroyt.lic   License file.
 

 

{
    "fileId": "469240e0-7376-49ce-90ea-8d254b69d2bd"
}

 

The description of the response payload:

 

Field Type Example Values Description
fileId string 6651aef5-e738-411f-8675-5f6b7b9cd429 File Id

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

POST a license token/code/ID (BYOL)

POST /ne/v1/device/license/{virtualDeviceUUID}

 Method  POST
 URL or End Point  /ne/v1/device/license/{virtualDeviceUUID}
 Headers  Authorization, Content-Type
 Path Parameter  virtualDeviceUUID
 Body Parameter  token

 

You can use this API to update a token/code/ID that is about to expire. Palo Alto devices need a license token. 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

Curl request to post a token:

curl -X

POST "https://api.equinix.com/ne/v1/device/license/9a47a75e-164b-4c1c-8678-7b3605d4dd32"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d "{
"token": "V74191621"
}"

 

The description of the path parameter is as follows:

 

Path Parameter Name Mandatory Type Example Applicable Values Description
VirtualDeviceUUID Yes string 9a47a75e-164b-4c1c-8678-7b3605d4dd32

 

UUID of virtual device
 

 

Body Parameter Name Mandatory Type Example Applicable Values Description
token Yes string V74191621   License token/Code/ID. This field must have 8 alphanumeric characters.

 

202 Accepted

 

The description of the response payload is as follows:

 

HTTP status Type Example Values Description
202 Accepted     Token/code/ID was accepted. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET virtual devices

GET /ne/v1/device

 Method  GET
 URL or End Point  /ne/v1/device
 Headers  Authorization, Content-Type
 Query Parameters  page, size, metroCode, status
 Body  Not applicable

 

Call this API to find out the details of your available virtual devices on the Equinix platform.

 

To retrieve drafts, you can query for devices with the status=DRAFT.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request and its respective JSON response to obtain available devices. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device?page=1&size=20&metroCode=DC&status=PROVISIONED"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Query Parameter Name Mandatory Type Example Applicable Values Description
page No string 1   Page number. Default value=1
size No string 100   Results per page. Default value=100
metroCode No string DC   Metro for which you want virtual devices.
status No string INITIALIZING INITIALIZING, PENDING_ACCOUNT, PROVISIONING, WAITING_FOR_PRIMARY, WAITING_FOR_SECONDARY, PROVISIONED, FAILED, DEPROVISIONING, DEPROVISIONED, DRAFT Status of the virtual device. 

 

Sample response: 

 

{
    "totalCount": 1,
    "pageNumber": 1,
    "pageSize": 1,
    "content": [
      {
            "uuid": "b9d2c2a1-3517-4af2-b35c-e2228fe05256",
            "name": "Router",
            "deviceTypeCode": "CSR1000V",
            "deviceTypeName": "CSR 1000V",
            "deviceTypeVendor": "Cisco",
            "deviceTypeCategory": "ROUTER",
            "status": "PROVISIONED",
            "licenseStatus": "REGISTERED",
            "metroCode": "SV",
            "metroName": "Silicon Valley",
            "ibx": "SV5",
            "region": "AMER",
            "throughput": 1,
            "throughputUnit": "Gbps",
            "hostName": "test",
            "packageCode": "IPBASE",
            "packageName": "IP Base",
            "licenseType": "Sub",
            "licenseName": "Subscription",
            "createdBy": "reseller1",
            "createdDate": "2019-09-27T07:40:38.887Z",
            "lastUpdatedBy": "reseller1",
            "lastUpdatedDate": "2019-09-30T17:36:05.523Z",
            "deviceSerialNo": "9TUGOHYGM26",
            "accountNumber": "5710199",
            "accountName": "sub1",
            "notifications": [
                "shakhan@ap.equinix.com"
            ],
            "redundancyType": "PRIMARY",
            "termLength": 1,
            "additionalBandwidth": 60,
            "interfaces": [
                {
                    "id": 1,
                    "name": "GigabitEthernet1",
                    "status": null,
                    "operationalStatus": null,
                    "macAddress": null,
                    "ipAddress": null,
                    "assignedType": "Equinix Managed"
                },
                {
                    "id": 2,
                    "name": "GigabitEthernet2",
                    "status": null,
                    "operationalStatus": null,
                    "macAddress": null,
                    "ipAddress": null,
                    "assignedType": "Equinix Managed"
                },
                {
                    "id": 3,
                    "name": "GigabitEthernet3",
                    "status": "RESERVED",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3e2d.4209",
                    "ipAddress": null,
                    "assignedType": "Connection to Network Service Provider"
                },
                {
                    "id": 4,
                    "name": "GigabitEthernet4",
                    "status": "AVAILABLE",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3ee9.46e4",
                    "ipAddress": null,
                    "assignedType": ""
                },
                {
                    "id": 5,
                    "name": "GigabitEthernet5",
                    "status": "AVAILABLE",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3edd.9efc",
                    "ipAddress": null,
                    "assignedType": ""
                },
                {
                    "id": 6,
                    "name": "GigabitEthernet6",
                    "status": "AVAILABLE",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3ef7.9dbf",
                    "ipAddress": null,
                    "assignedType": ""
                },
                {
                    "id": 7,
                    "name": "GigabitEthernet7",
                    "status": "AVAILABLE",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3ec5.0bf7",
                    "ipAddress": null,
                    "assignedType": ""
                },
                {
                    "id": 8,
                    "name": "GigabitEthernet8",
                    "status": "AVAILABLE",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3e5c.6bb2",
                    "ipAddress": null,
                    "assignedType": ""
                },
                {
                    "id": 9,
                    "name": "GigabitEthernet9",
                    "status": "AVAILABLE",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3e88.276d",
                    "ipAddress": null,
                    "assignedType": ""
                },
                {
                    "id": 10,
                    "name": "GigabitEthernet10",
                    "status": "AVAILABLE",
                    "operationalStatus": "down",
                    "macAddress": "fa16.3e0a.198e",
                    "ipAddress": null,
                    "assignedType": ""
                }
            ]
        }
            
        
    ]
}

 

The description of the response is as follows:

 

Field Name Type Example Values Description
pageSize integer 20 Results per page.
pageNumber integer 5 Page number.
totalCount integer 200 Total count.
content content[]   An array of virtual device objects
uuid string ec68e425-f973-452e-a866-76be5844d0ba Unique ID of the virtual device (UUID).
name string Test-device-003-SROY Name of the virtual device.
deviceTypeCode string CSR1000V Device type code.
deviceTypeName string CSR 1000V Device type name.
deviceTypeVendor string Cisco Vendor of the device.
deviceTypeCategory string ROUTER Category of the device.
status string PROVISIONED Status of the device. 
licenseStatus string REGISTERED Status of the license. 
expiry string Never License expiry.
metroCode string DC Metro where the device is located.
metroName string Ashburn Metro name.
ibx string DC1 Name of Equinix exchange. One metro may have several exchanges.
region string AMER The region in which the metro is located
throughput integer 500 Throughput of the device
throughputUnit string Mbps Throughput unit.
hostName string TC12 Host name.
packageCode string SEC Software package code.
packageName string Security Software package name.
licenseType string BYOL Type of license, whether BYOL or subscription.
licenseName string Bring Your Own License Name of license.
licenseFileld string 9125e24a-708b-4c6e-8694-2c3ca727b081 License file Id. You get a licenseFileId when you upload a license file from your vendor to Equinix.
createdBy string myna Created by.
createdDate string 2019-05-03T03:11:44.127Z Creation date.
lastUpdatedBy string myna Last updated by.
lastUpdatedDate string 2019-05-03T03:11:44.127Z Last update date.
deviceSerialNo string 92CONAW32JC The serial number of the device.
accountNumber string 2252619 Account number.
accountName string nfv-sit1 Account name.
notifications array[] test@equinix.com List of email addresses that will receive device life-cycle notifications.
purchaseOrderNumber string 3456778 Customer's purchase order number.
redundancyType string PRIMARY Whether this device is primary or secondary. Secondary (HA) devices are redundant devices that ensure high availability.
redundantUUID string 086d0425-69b7-4c8e-8a29-a3d5a1e543da Unique Id of the redundant device. If this device is primary, then this field will have the unique Id of the secondary (HA) device. Otherwise, if this device is a secondary device, then this will field will have the unique Id of the primary device. 
managementIp string 10.198.251.54/24 Management IP. This optional parameter is relevant for SD-WAN devices. 
managementGatewayIp string 10.198.251.1 Management Gateway IP. This optional parameter is relevant for SD-WAN devices. 
publicIp string 149.97.198.97/31 Public IP. This optional parameter is relevant for SD-WAN devices. 
publicGatewayIp string 149.97.198.96 Public Gateway IP. This optional parameter is relevant for SD-WAN devices. 
primaryDnsName string 4.0.0.53 Primary DNS name. This optional parameter is relevant for SD-WAN devices. 
secondaryDnsName string 129.250.35.250 Secondary DNS name. This optional parameter is relevant for SD-WAN devices. 
termLength integer 24 The length of the contract.
additionalBandwidth integer 100 Additional bandwidth in Mbps.
vendorConfig object vendorConfig {siteId, systemIpAddress } The vendor config object has parameters that are specific to vendors. A Cisco SD-WAN device will have siteId and systemIpAddress. 
siteId string 567 Site Id. Relevant only for Cisco SD-WAN devices. A siteId is a particular physical location within the Viptela overlay network, such as a branch office, or a campus. 
systemIpAddress string 2.2.2.2 System IP address. Relevant only for Cisco SD-WAN devices. Each CSRSDWAN router and vSmart controller is assigned a system IP address. 
licenseKey string 1404-991d81bb-2567-43e5-a14c-1493ace58046 License key (ION key). Relevant only for CloudGenix devices.
licenseSecret string d29dceeef2d2b494c9eb76937a361890786e609d License secret (Secret key). Relevant only for CloudGenix devices. 
localId string SDWAN-Branch@Versa.com Email address of the branch location. Relevant only for Versa SD-WAN devices.
remoteId string Controller-01-staging@Versa.com Email address of the controller side. Relevant only for Versa SD-WAN devices.
controller1 string 54.219.248.29 Ip address of the SD-WAN controller1. Relevant only for Versa SD-WAN devices.
controller2 string 54.177.220.115 Ip address of the SD-WAN controller2. Relevant only for Versa SD-WAN devices.
serialNumber string 4545454 The customer selects a serial number when setting up the device template on Versa director. Relevant only for Versa SD-WAN devices. 
interfaces array[object]   An array of interface objects. 
id integer 1 Id of the interface.
name string GigabitEthernet1 Name of the interface.
status string AVAILABLE Status of the interface, whether it is AVAILABLE, RESERVED or ASSIGNED. Assigned interfaces are already in use. Reserved interfaces can only be used to bring your own connection (BYOC) from your Network Service Providers. 
operationStatus string down Operation status of the interface, whether it is up or down.
macAddress string fa16.3e1c.a8d8 Media access control address. It is the hardware identification number that uniquely identifies each device on a network. 
ipAddress string 2.2.2.2 Ip address.
assignedType string Equinix Managed  

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

GET virtual device {UUID}

GET /ne/v1/device/{uuid}

 Method  GET
 URL or End Point  /ne/v1/device/{uuid}
 Headers  Authorization, Content-Type
 Path Parameter  UUID
 Body  Not applicable

 

Call this API to get a virtual device by its unique Id (UUID) on the Equinix platform.

 

To retrieve a draft, provide the unique Id of the draft (draftUUID).

 

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

 

The following screenshots show a sample curl request and its respective JSON response to get a virtual device. 

 

curl -X

GET "https://api.equinix.com/ne/v1/device/01425e3b-0e37-4539-af09-5b26cb9bad18"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Path Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string ec68e425-f973-452e-a866-76be5844d0ba   Unique ID of the virtual device. To retrieve a draft, provide the unique Id of the draft (draftUUID).

 

Sample response: 

 

{
    "uuid": "01425e3b-0e37-4539-af09-5b26cb9bad18",
    "name": "Auto_oct_csr_10/1",
    "deviceTypeCode": "CSR1000V",
    "deviceTypeName": "CSR 1000V",
    "deviceTypeVendor": "Cisco",
    "deviceTypeCategory": "ROUTER",
    "status": "PROVISIONED",
    "licenseStatus": "REGISTERED",
    "metroCode": "SV",
    "metroName": "Silicon Valley",
    "ibx": "SV5",
    "region": "AMER",
    "throughput": 1,
    "throughputUnit": "Gbps",
    "hostName": "myhost-2",
    "packageCode": "SEC",
    "packageName": "Security",
    "licenseType": "Sub",
    "licenseName": "Subscription",
    "createdBy": "nfv-sit1",
    "createdDate": "2019-10-02T18:17:26.058Z",
    "lastUpdatedBy": "nfv-sit1",
    "lastUpdatedDate": "2019-10-02T19:39:56.176Z",
    "acl": [
        "15.0.0.0/8",
        "10.202.10.25/32",
        "10.196.67.41/32"
    ],
    "sshIpAddress": "14.1.1.43",
    "deviceSerialNo": "9PQN48Q1VS9",
    "sshIpFqdn": "myhost-2-43-1-1-14-SV.eis.lab.equinix.com",
    "accountNumber": "3240199",
    "accountName": "nfv-sit1",
    "notifications": [
        "anarausetty@equinix.com"
    ],
    "redundancyType": "PRIMARY",
    "termLength": 1,
    "additionalBandwidth": 200,
    "interfaces": [
        {
            "id": 1,
            "name": "GigabitEthernet1",
            "status": null,
            "operationalStatus": null,
            "macAddress": null,
            "ipAddress": null,
            "assignedType": "Equinix Managed"
        },
        {
            "id": 2,
            "name": "GigabitEthernet2",
            "status": null,
            "operationalStatus": null,
            "macAddress": null,
            "ipAddress": null,
            "assignedType": "Equinix Managed"
        },
        {
            "id": 3,
            "name": "GigabitEthernet3",
            "status": "RESERVED",
            "operationalStatus": "down",
            "macAddress": "fa16.3e56.440c",
            "ipAddress": null,
            "assignedType": "Connection to Network Service Provider"
        },
        {
            "id": 4,
            "name": "GigabitEthernet4",
            "status": "ASSIGNED",
            "operationalStatus": "up",
            "macAddress": "fa16.3ec6.724e",
            "ipAddress": "14.1.4.9/30",
            "assignedType": "conn_1(NE-SellerProfile-L2-SV-1)"
        },
        {
            "id": 5,
            "name": "GigabitEthernet5",
            "status": "ASSIGNED",
            "operationalStatus": "up",
            "macAddress": "fa16.3ef5.dd86",
            "ipAddress": "14.2.5.9/30",
            "assignedType": "conn_3(NE-SellerProfile-L2-SV-1)"
        },
        {
            "id": 6,
            "name": "GigabitEthernet6",
            "status": "AVAILABLE",
            "operationalStatus": "down",
            "macAddress": "fa16.3e03.14fc",
            "ipAddress": null,
            "assignedType": ""
        },
        {
            "id": 7,
            "name": "GigabitEthernet7",
            "status": "AVAILABLE",
            "operationalStatus": "down",
            "macAddress": "fa16.3ef3.91a3",
            "ipAddress": null,
            "assignedType": ""
        },
        {
            "id": 8,
            "name": "GigabitEthernet8",
            "status": "AVAILABLE",
            "operationalStatus": "down",
            "macAddress": "fa16.3e8c.b071",
            "ipAddress": null,
            "assignedType": ""
        },
        {
            "id": 9,
            "name": "GigabitEthernet9",
            "status": "AVAILABLE",
            "operationalStatus": "down",
            "macAddress": "fa16.3e1f.0e1d",
            "ipAddress": null,
            "assignedType": ""
        },
        {
            "id": 10,
            "name": "GigabitEthernet10",
            "status": "AVAILABLE",
            "operationalStatus": "down",
            "macAddress": "fa16.3e12.1d1e",
            "ipAddress": null,
            "assignedType": ""
        }
    ]
}

 

The description of the response is as follows:

 

Field Name Type Example Values Description
uuid string ec68e425-f973-452e-a866-76be5844d0ba Unique ID of the virtual device (UUID).
name string Test-device-003-SROY Name of the virtual device.
deviceTypeCode string CSR1000V Device type code.
deviceTypeName string CSR 1000V Device type name.
deviceTypeVendor string Cisco Vendor of the device.
deviceTypeCategory string ROUTER Category of the device.
status string PROVISIONED Status of the device. 
licenseStatus string REGISTERED Status of the license. 
metroCode string DC Metro where the device is located.
metroName string Ashburn Metro name.
ibx string DC1 Name of the Equinix exchange. A metro location may have several exchanges. 
region string AMER The region in which the metro is located
throughput integer 500 Throughput of the device
throughputUnit string Mbps Throughput unit.
hostName string TC12 Host name.
packageCode string SEC Software package code.
packageName string Security Software package name.
licenseType string BYOL Type of license, whether BYOL or subscription.
licenseName string Bring Your Own License Name of license.
licenseFileld string 9125e24a-708b-4c6e-8694-2c3ca727b081 License file Id. You get a licenseFileId when you upload a license file from your vendor to Equinix.
createdBy string myna Created by.
createdDate string 2019-05-03T03:11:44.127Z Creation date.
lastUpdatedBy string myna Last updated by.
lastUpdatedDate string 2019-05-03T03:11:44.127Z Last update date.
acl array[] acl [14.2.2.10] Access control list. These IP addresses can access the device.
sshIpAddress string 101.97.33.201 Ip Address of the device. 
deviceSerialNo string 92CONAW32JC The serial number of the device.
sshIpFqdn string

testhost-201-33-97-101-SY.eis.lab.equinix.com

The fully qualified domain name of the device. 
accountNumber string 2252619 Account number.
accountName string nfv-sit1 Account name.
notifications array[] test@equinix.com List of email addresses that will receive notifications.
purchaseOrderNumber string 3456778 Customer's purchase order number.
redundancyType string PRIMARY Whether this device is primary or secondary. Secondary (HA) devices are redundant devices that ensure high availability.
redundantUUID string 086d0425-69b7-4c8e-8a29-a3d5a1e543da Unique Id of the redundant device. If this device is primary, then this field will have the unique Id of the secondary (HA) device. Otherwise, if this device is a secondary device, then this will field will have the unique Id of the primary device. 
managementIp string 10.198.251.54/24 Management IP. This is an optional parameter relevant for SDWAN devices. 
managementGatewayIp string 10.198.251.1 Management Gateway IP. This is an optional parameter relevant for SDWAN devices. 
publicIp string 149.97.198.97/31 Public IP. This is an optional parameter relevant for SDWAN devices. 
publicGatewayIp string 149.97.198.96 Public Gateway IP. This is an optional parameter relevant for SDWAN devices. 
primaryDnsName string 4.0.0.53 Primary DNS name. This is an optional parameter relevant for SDWAN devices. 
secondaryDnsName string 129.250.35.250 Secondary DNS name. This is an optional parameter relevant for SDWAN devices. 
termLength integer 24 The term length of the contract.
additionalBandwidth integer 100 Additional bandwidth in Mbps.
vendorConfig object vendorConfig {siteId, systemIpAddress } The vendor config object has parameters that are specific to vendors. A Cisco SD-WAN device will have siteId and systemIpAddress. 
siteId string 567 Site Id. Relevant only for Cisco SD-WAN devices. A siteId is a particular physical location within the Viptela overlay network, such as a branch office, or a campus. 
systemIpAddress string 2.2.2.2 System IP address. Relevant only for Cisco SD-WAN devices. Each CSRSDWAN router and vSmart controller is assigned a system IP address. 
licenseKey string 1404-991d81bb-2567-43e5-a14c-1493ace58046 License key (ION key). Relevant only for CloudGenix devices.
licenseSecret string d29dceeef2d2b494c9eb76937a361890786e609d License secret (Secret key). Relevant only for CloudGenix devices. 
localId string branch1@example.com Email address of the branch location. Relevant only for Versa SD-WAN devices.
remoteId string companyController1@example.com Email address of the controller side. Relevant only for Versa SD-WAN devices.
controller1 string 54.219.248.29 Ip address of the SD-WAN controller1. Relevant only for Versa SD-WAN devices.
controller2 string 54.177.220.115 Ip address of the SD-WAN controller2. Relevant only for Versa SD-WAN devices.
serialNumber string 4545454 The customer selects a serial number when setting up the device template on Versa director. Relevant only for Versa SD-WAN devices. 
interfaces array[object]   An array of interface objects. 
id integer 1 Id of the interface.
name string GigabitEthernet1 Name of the interface.
status string AVAILABLE Status of the interface, whether it is AVAILABLE, ASSIGNED, or RESERVED. Assigned interfaces are already in use. Reserved interfaces can only be used to bring your own connection (BYOC) from your Network Service Providers. 
operationStatus string down Operation status of the interface, whether it is up or down.
macAddress string fa16.3e1c.a8d8 Media access control address. It is the hardware identification number that uniquely identifies each device on a network. 
ipAddress string 2.2.2.2 Ip address.
assignedType string Equinix Managed  

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

DELETE virtual device by UUID

DELETE /ne/v1/device/{uuid}

 Method  DELETE
 URL or End Point  /ne/v1/device/{uuid}
 Headers  Authorization, Content-Type
 Query Parameter  deleteRedundantDevice
 Path Parameter  uuid
 Body deactivationKey

 

Call this API to delete a virtual device on the Equinix platform.

 

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

 

The following screenshots show a sample curl request and its respective JSON response. 

 

curl -X

DELETE "https://api.equinix.com/ne/v1/device/5f888d91-d2c5-45bb-9b51-fed99f57f0ac?deleteRedundantDevice=True"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Path Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string 5f888d91-d2c5-45bb-9b51-fed99f57f0ac   Unique ID of the virtual device.

 

 

Query Parameter Name Mandatory Type Example Applicable Values Description
deleteRedundantDevice No Boolean True   Optional parameter in case you have a secondary device for high availability (HA). As both primary and secondary devices are deleted simultaneously, this field must be marked True for Equinix to successfully delete a device that has a secondary device.

 

 

Body Parameter Name Mandatory Type Example Applicable Values Description
deactivationKey   string 8dfbd5ba3610234d9e550032603cc34762af140533e2c1de0111d3451d16eefd   Some devices, e.g. Palo Alto devices, require a mandatory deactivation key for Equinix to successfully process the request. 
 
secondary   object     Object that holds the secondary deactivation key for HA (high availability) devices. 

 

Sample response: 

 

202 : Deletion requested accepted.

 

The description of the response is as follows:

 

HTTP status Description
202 Deletion request successfully accepted.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

PUT ACL (Access IP addresses)

PUT /ne/v1/device/{uuid}/acl

 Method  PUT
 URL or End Point  /ne/v1/device/{uuid}/acl
 Headers  Authorization, Content-Type
 Path Parameter  uuid
 Body Parameter  Array of IP addresses in CIDR format

 

Call this API to update/add a list of ACL (Acess IP addresses) to a virtual device. 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

curl -X

PUT "https://api.equinix.com/ne/v1/device/f61e75d2-2008-43f4-bfee-1dd17b1e1a28/acl"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d "

["192.168.1.1/32"]

"

 

The description of the body parameter:

 

Parameter Name Mandatory Type Example Applicable Values Description
acl Yes array ["192.168.1.1/32"]

 

Access IP addresses in CIDR format. You may have upto fifty addresses.

 

204 No content

 

The description of the response payload:

 

HTTP status Description
204 No content The request was processed.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

POST SSH user

POST /ne/v1/services/ssh-user

 Method  POST
 URL or End Point  /ne/v1/services/ssh-user
 Headers  Authorization, Content-Type
 Path Parameters  NA
 Body Parameters  username, password, deviceUuid

 

Call this API to create a new shh user and associate the user to a virtual device. You can only associate a user to an active device. 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

Curl request:

 

curl -X

POST "https://api.equinix.com/ne/v1/services/ssh-user"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d "{
"username": "SRT12345",

"password": "projPass",

"deviceUuid": "3da0a663-20d9-4b8f-8c5d-d5cf706840c8"

}"

 

The description of the body parameters is as follows:

 

Parameter Name Mandatory Type Example Applicable Values Description
username Yes string srt12345

 

User name.
password Yes string projPass   Password.
deviceUuid Yes string 3da0a663-20d9-4b8f-8c5d-d5cf706840c8   Unique Id of the virtual device.

 

Sample response

 

{
    "uuid": "4da0a663-20d9-4b8f-8c5d-d5cf706840c9"
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
uuid string 4da0a663-20d9-4b8f-8c5d-d5cf706840c9 Unique Id of the newly created ssh user.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET SSH Users

GET /ne/v1/services/ssh-user

 Method  GET
 URL or End Point  /ne/v1/services/ssh-user
 Headers  Authorization, Content-Type
 Query Parameters  username, virtualDeviceUUID, verbose, pageNumber, pageSize
 Body  Not applicable

 

Call this API to find out SSH user details.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request. 

 

curl -X

GET "https://api.equinix.com/ne/v1/services/ssh-user?verbose=Yes"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Query Parameter Name Mandatory Type Example Applicable Values Description
username No string sr3245   Ssh user name. 
virtualDeviceUUID No string 32cf4a21-a6c4-4501-9a0c-79fc0873f653   Unique Id of the virtual device
verbose No boolean True True, False Whether you want details, including virtual device UUID, metros, or just the unique Id and username of ssh users.
pageNumber No integer 0   Page number.
pageSize No integer 20   Number of results per page.

 

Sample response: 

 

{
    "totalCount": 1,
    "pageNumber": 0,
    "pageSize": 20,
    "list": [
        {
            "uuid": "d8fe1db2-75a1-436e-839f-3ca50f4dce87",
            "username": "SRT12345",
            "deviceUuids": [
                "3925b42b-eff6-4c07-8c1a-3f16c01779aa"
            ],
            "metroStatusMap": {
                "SV": {
                    "status": "ACTIVE"
                }
            }
        }
    ],
    "content": null
}

 

The description of the response is as follows:

 

Field Name Type Example Values Description
totalCount integer 5

Total number of results.

pageNumber integer 0 Page number.
pageSize integer 20 Number of results per page.
list array   An array of ssh users.
uuid string 32cf4a21-a6c4-4501-9a0c-79fc0873f653 Unique Id of the ssh user.
username string srt123 Ssh user name.
deviceUuids array "deviceUuids": [
        "3925b42b-eff6-4c07-8c1a-3f16c01779aa"
    ]
An array of virtual device unique Ids associated with the username.
metroStatusMap object  "metroStatusMap": {
        "SV": {
            "status": "ACTIVE"
        }
    }
Object with the metro name as the key. The value is another object that has the status (PENDING, ACTIVE, or FAILED) of the ssh user in that metro. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

GET SSH user {uuid}

GET /ne/v1/services/ssh-user/{uuid}

 Method  GET
 URL or End Point  /ne/v1/services/ssh-user/{uuid}
 Headers  Authorization, Content-Type
 Path Parameter  uuid
 Body  Not applicable

 

Call this API to get SSH user details by unique Id of the ssh user.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request. 

 

curl -X

GET "https://api.equinix.com/ne/v1/services/ssh-user/d8fe1db2-75a1-436e-839f-3ca50f4dce89"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Path Parameter Name Mandatory Type Example Applicable Values Description
uuid Yes string

d8fe1db2-75a1-436e-839f-3ca50f4dce89

  Unique Id of the SSH user. 

 

Sample response: 

 

{
    "uuid": "d8fe1db2-75a1-436e-839f-3ca50f4dce87",
    "username": "SRT12345",
    "deviceUuids": [
        "3925b42b-eff6-4c07-8c1a-3f16c01779aa"
    ],
    "metroStatusMap": {
        "SV": {
            "status": "ACTIVE"
        }
    }
}

 

The description of the response is as follows:

 

Field Name Type Example Values Description
uuid string 32cf4a21-a6c4-4501-9a0c-79fc0873f653 Unique Id of the ssh user.
username string srt123 Ssh user name.
deviceUuids array  "deviceUuids": [
        "3925b42b-eff6-4c07-8c1a-3f16c01779aa"
    ]
An array of virtual device unique Ids associated with the username.
metros object "metroStatusMap": {
        "SV": {
            "status": "ACTIVE"
        }
    }
An object with the metro name as the key. The value is another object that has the status (PENDING, ACTIVE, or FAILED) of the ssh user in that metro. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

DEL SSH User from a device

DEL /ne/v1/services/ssh-user/{uuid}/association

 Method  DEL
 URL or End Point  /ne/v1/services/ssh-user/{uuid}/association
 Headers  Authorization, Content-Type
 Path Parameter  uuid
 Query Parameter  deviceUuid

 

Call this API to dissociate an SSH user from a device. The ssh user is deleted if there is no other device associated with it.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshot shows a sample curl request. 

 

curl -X

DEL "https://api.equinix.com/ne/v1/services/ssh-user/d8fe1db2-75a1-436e-839f-3ca50f4dce87/association?deviceUuid=9ae1e9fc-7b0b-453b-bf2e-ea1d5fc52753"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Path Parameter Name Mandatory Type Example Applicable Values Description
uuid Yes string d8fe1db2-75a1-436e-839f-3ca50f4dce89

 

Unique Id of the ssh user.

 

 

Query Parameter Name Mandatory Type Example Applicable Values Description
deviceUuid Yes string 9ae1e9fc-7b0b-453b-bf2e-ea1d5fc52753

 

Unique Id of the virtual device.

 

Sample response: 

 

{
  "sshUserDeleted": false,
  "sshUserToDeviceAssociationDeleted": true
}

 

The description of the response:

 

Field Name Type Example Values Description
sshUserDeleted string false Whether the ssh user was deleted or not. The ssh user is deleted from the system only if there is no other device associated with the user. 
sshUserToDeviceAssociationDeleted string true Whether the ssh user was removed from the device. If True, the user will no longer have access to the device. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

GET L2 Service Profiles

GET /ne/v1/l2/serviceprofiles/services

 Method  GET
 URL or End Point  /ne/v1/l2/serviceprofiles/services
 Headers  Authorization, Content-Type
 Query Parameters  metroCode, pageNumber, pageSize
 Body  Not applicable

 

The service API returns all L2 seller profiles (services), such as AWS - Direct Connect, Azure - Express Route, for a given metro.

 

To obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to obtain details of L2 sellers within DC, USA and a JSON response containing details of a sample seller named John-Doe Demo. 

 

curl -X

GET "https://api.equinix.com/ne/v1/l2/serviceprofiles/services?pageSize=20&pageNumber=0&metroCode=Dc"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
pageSize No Integer 20   The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
pageNumber No Integer 1   The page number of the page which is currently being displayed. 
metroCode No array[string]

DC

 

The 2 character metro code of the metro for which to retrieve service profiles. It can be a single code (&metroCode=Dc) or an array of codes (&metroCode=Dc&metroCode=Sv). 

 

{
    "isLastPage": false,
    "totalCount": 23,
    "isFirstPage": true,
    "pageSize": 20,
    "content": [
        {
            "uuid": "97d1850f-4df0-468c-9281-fa7b0dfa2096",
            "name": "John-Doe Demo",
            "connectionNameLabel": "JohnDoeConnection",
            "requiredRedundancy": false,
            "allowCustomSpeed": false,
            "speedBands": [
                {
                    "speed": 50,
                    "unit": "MB"
                },
                {
                    "speed": 200,
                    "unit": "MB"
                },
                {
                    "speed": 500,
                    "unit": "MB"
                },
                {
                    "speed": 1000,
                    "unit": "MB"
                }
            ],
            "metros": [
                {
                    "code": "SV",
                    "name": "Silicon Valley",
                    "ibxs": [
                        "SV5"
                    ],
                    "displayName": "Silicon Valley"
                },
                {
                    "code": "DC",
                    "name": "Ashburn",
                    "ibxs": [
                        "DC11"
                    ],
                    "displayName": "Ashburn"
                }
            ],
            "createdDate": "2018-12-07T13:31:58.525Z",
            "createdBy": "John-Doe",
            "lastUpdatedDate": "2018-12-07T13:58:28.258Z",
            "lastUpdatedBy": "John-Doe",
            "vlanSameAsPrimary": false,
            "tagType": "BOTH",
            "apiAvailable": false,
            "selfProfile": false,
            "speedFromAPI": false,
            "profileEncapsulation": "Qinq",
            "authorizationKey": "[a-z|A-z|0-9]",
            "organizationName": "John-Doe-Corp",
            "private": false,
            "features": {
                "cloudReach": true,
                "testProfile": false
            }
        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
isLastPage boolean

true

false

Indicates whether the page being displayed is the last page.
totalCount integer 23 The number of items returned as response for the API request.
isFirstPage boolean

true

false

Indicates whether the page being displayed is the first page.
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content array   An array containing the response data.
uuid string 97d1850f-4df0-468c-9281-fa7b0dfa2096 The unique identifier of the service profile.
name string John-Doe Demo The name assigned to the service profile.
connectionNameLabel string JohnDoeConnection This is the label the user will see when creating a connection name for their connection.
requiredRedundancy boolean

true

false

Indicates whether or not redundant connections are required when connecting to this service profile.

If requireRedundancy” = true, you would need two ports, a primary port with a primary connection and a secondary port with a secondary connection, or one port and two connections (one primary and one secondary).

allowCustomSpeed boolean

true

false

Indicates whether or not to allow custom bandwidths/speeds to be defined when creating connections to this profile.
speedBands array   An array containing the speeds/bandwidth ranges allowed when creating connections to this profile.
speed double

50

200

500

1000

Bandwidth speed.
unit string MB Bandwidth speed unit.
metros array   The metros associated with this profile where connections can be created.
code string SV The metro code denoting metros where connections to this service profile can be created.
name string Silicon Valley The actual metro name where connections to this service profile can be created.
ibxs string SV5 Equinix IBXs associated with this metro.
displayName string Silicon Valley The name displayed when referring to this metro.
createdDate string 2018-12-07T13:31:58.525Z The date the service profile was created.
createdBy string John-Doe The username who created the service profile.
lastUpdatedDate string 2018-12-07T13:58:28.258Z The last date the service profile was updated.
lastUpdatedBy string John-Doe The user who last updated the service profile.
vlanSameAsPrimary boolean

true

false

Indicates whether or not to use the same VLAN for the primary connection as for the secondary connection.
tagType string

CTAGED

BOTH

NAMED

The type of tagging to be used for connections to this service profile. The default value is CTAGED.
apiAvailable boolean

true

false

Indicates whether or not API integration has been performed for connections to this profile.
selfProfile boolean

true

false

Indicates whether the profile belongs to your organization.
speedfromAPI string

true

false

Bandwidth of the cloud service provider for this connection according to the service provider.
profileEncapsulation string

Dot1q

Qinq

The port encapsulation type for this profile, can be either Dot1q or Qinq.
authorizationKey string [a-z|A-z|0-9] A sample authorization key expression to be used by the user/customer when creating connections to this profile. e.g. - Account ID for AWS, Service key for Azure, etc
organizationName string John-Doe-Corp Organization name associated with this service profile.
private boolean

true

false

Indicates whether or not this is a private profile. If private, it can only be available for creating connections if correct permissions are granted (i.e. not public like AWS/Azure/Oracle/Google, etc.)
features object   Contains feature related information such as cloudReach, testProfile, etc.  
cloudReach boolean

true

false

Indicates whether or not connections to this profile can be created from remote metros.
testProfile boolean

true

false

Indicates whether or not this profile can be used for test connections.
pageNumber integer 0 The page number of the page which is currently being displayed. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

 GET L2 Validate Authorization Key

GET /ne/v1/l2/connections/validateAuthorizationKey

 Method  GET
 URL or End Point  /ne/v1/l2/connections/validateAuthorizationKey
 Headers  Authorization, Content-Type
 Query Parameters  authorizationKey,metroCode, profileId, region 
 Body  Not applicable

 

The validateAuthorizationKey API validates an L2 service key against an L2 destination service profile. In other words,  this API checks if the user is authorized by the service provider to create a connection to this metro (destination).

 

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

 

The following screenshots show a sample curl request to validate an L2 service key against a service profile in DC, and its respective JSON response. 

 

curl -X

GET "https://api.equinix.com/ne/v1/l2/connections/validateAuthorizationKey?authorizationKey=991040a8-2e08-48b9-b0f8-8c5f87dfbx6a&metroCode=DC&profileId=x1384t22-bbe0-4e43-ax37-95beeg9d254d&region=AMER

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
authorizationKey Yes string 991040a8-2e08-48b9-b0f8-8c5f87cfbx6a   Connection credentials such as AWS account ID for AWS, service key for Azure etc.
metroCode Yes string DC

 

The two-character code used to denote the metro.

profileId Yes string x1384t22-bbe0-4e43-ax37-95beeg9d254d   The unique identifier of the service profile.
region Yes string AMER

"AMER"

"EMEA"

"APAC"

Indicates the region in which the port resides.

 

{
    "message": "Authorization key provided is valid",
    "status": "VALID",
    "primary": {
        "bandwidth": "50MB"
    },
    "secondary": {
        "bandwidth": "50MB"
    }
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Authorization key provided is valid A message indicating whether the submitted key is valid or invalid.
status string

VALID

INVALID

Indicates whether the submitted key is valid or invalid.
primary object  

An object containing primary connection information.

bandwidth string 50MB The bandwidth of the primary connection.
secondary object   An object containing secondary connection information.
bandwidth string 50MB The bandwidth of the secondary connection.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET L2 Connections {connId}

GET l2/connections/{connid}

 Method  GET
 URL or End Point  /ne/v1/l2/connections/{connId}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable
 Path Parameter  connId

 

The connections API returns connection details for a given L2 connection unique Id.

 

ConnId is an identifier unique for each connection.

 

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

 

The following screenshots show a sample curl request to obtain L2 connection details for the ID 97d1850f-4df0-468c-9281-fa7b0dfa2096 and a JSON response containing connection information. 

 

curl -X

GET "https://api.equinix.com/ne/v1/l2/connections/006d08e2-788e-4c83-82d3-07b1787644a5"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "isFirstPage": true,
    "totalCount": 467,
    "isLastPage": false,
    "pageSize": 20,
    "content": [
        {
            "buyerOrganizationName": "JOHN-DOE-ORG",
            "uuid": "006d08e2-788e-4c83-82d3-07b1787644a5",
            "name": "John-Doe",
            "vlanSTag": 200,
            "portUUID": "66284add-86d1-6d10-b4e0-30ac094f8af1",
            "portName": "JOHN-DOE-PORT",
            "asideEncapsulation": "dot1q",
            "metroCode": "TR",
            "metroDescription": "Toronto",
            "providerStatus": "DEPROVISIONED",
            "status": "DEPROVISIONED",
            "billingTier": "Up to 50 MB",
            "authorizationKey": "12238-36f9-47f8-c12g-afr33af02d06",
            "speed": 50,
            "speedUnit": "MB",
            "redundancyType": "secondary",
            "redundancyGroup": "28c02121-f093-4340-90c9-081b17b239c8",
            "sellerMetroCode": "TR",
            "sellerMetroDescription": "Toronto",
            "sellerServiceName": "Azure Express Route",

            "sellerServiceUUID": "a1390b22-bbe0-4e93-ad37-85beef9d254d",
            "sellerOrganizationName": "JOHN ORG",
            "notifications": [
                "JohnDoe@equinix.com"
            ],

            "namedTag": "Private",
            "createdDate": "2018-08-30T04:20:36.033Z",
            "createdBy": "JohnDoe@equinix.com",
            "createdByFullName": "John Doe",
            "createdByEmail": "JohnDoe@equinix.com",
            "lastUpdatedDate": "2018-09-14T02:21:06.425Z",
            "deletedBy": "JohnDoe@equinix.com",
            "deletedDate": "2018-09-02T16:03:36.349Z",
            "deletedByEmail": "JohnDoe@equinix.com",
            "zSidePortName": "JOHN-DOE-PORT-B",
            "zSidePortUUID": "6f5680ea-1513-5130-50e0-30ac094f83ec",
            "zSideVlanSTag": 8,
            "remote": false,
            "private": false,
            "self": false

        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

Field Type Example Description
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content object   An array containing the response data.
asideEncapsulation string

Dot1q

Qinq

The encapsulation of the buyer port (Dot1Q or QinQ).
authorizationKey string 1233548-36g9-47f8-b12f-afa3faf02d06 The authorization key to be used by the user/customer when creating connections to this profile.
billingTier string Up to 50 MB Billing tier for connection.
buyerOrganizationName string JOHN-DOE-ORG Buyer organization name.
createdBy string JohnDoe@equinix.com The username who created the connection.
createdByEmail string JohnDoe@equinix.com The email ID of the user who created the connection.
createdByFullName string John Doe The full name of the user who created the connection.
createdDate string 2018-08-30T04:20:36.033Z The date on which the connection was created.
lastUpdatedBy string   The username who updated the connection.
lastUpdatedDate string 2018-09-14T02:21:06.425Z The date on which the connection was last updated.
lastUpdatedByEmail string   The email ID of the user who updated the connection.
lastUpdatedByFullName string   The full name of the user who updated the connection.
namedTag string Private The type of peering you would like to set up with Azure Express Route.
notification array JohnDoe@equinix.com Email address of the contact to be notified for any updates on the connection.
metroCode string TR The metro code denoting the source metro from where the connection has been created. 
metroDescription string Toronto The metro name where connections to this service profile can be created. 
name string John-Doe Name of the connection.
namedTag string

"Private" 

"Public" 

"Microsoft" 

"Manual"

The type of peering for Azure Express Route.
portName string JOHN-DOE-PORT The name assigned to the port.
portUUID string 66284add-86d1-6d10-b4e0-30ac094f8af1 The unique identifier of the port.
private boolean

true

false

Indicates whether or not this is a private profile. If private, it can only be available for creating connections if correct permissions are granted (i.e. not public like AWS/Azure/Oracle/Google, etc.)
purchaseOrderNumber string   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
redundancyGroup string 28c02121-f093-4340-90c9-081b17b239c8 Grouping of a primary and secondary connection using a unique ID.
redundancyType string

"primary"

"secondary"

The type of connection.
remote boolean  

true

false

Indicates whether the connection is a remote connection.  (i.e. if the seller and buyer metros are different then it's a remote connection)
self boolean

true

false

Indicates whether the connection belongs to your organization. (i.e. source and destination belongs to your organization)
sellerMetroCode string TR The metro code denoting the destination metro where the connection has been created to. 
sellerMetroDescription string Toronto The metro name indicating the destination metro where the connection has been created to. 
sellerOrganizationName string JOHN ORG Seller organization name associated with the connection.
sellerServiceName string Azure Express Route Seller service associated with the connection.
sellerServiceUUID string a1390b22-bbe0-4e93-ad37-85beef9d254d Seller service ID associated with the connection.
speed integer 50 Bandwidth speed
speedUnit string

MB

GB

The unit of bandwidth speed.
providerStatus string

DEPROVISIONED

PROVISIONED

PENDING_APPROVAL

NOT_AVAILABLE

DEPROVISIONING

PROVISIONING

FAILED

PENDING_BGP

AVAILABLE

OUTOFBANDWIDTH

ERROR

The status of the connection at the service provider's end.
status string DEPROVISIONED The status of the connection at Equinix's end.
uuid string 006d08e2-788e-4c83-82d3-07b1787644a5 The unique identifier of the connection.
vlanSTag string 5 Stag name of the connection.
zSidePortName string JOHN-DOE-PORT-B"

The name of the Z side port.

zSidePortUUID string 66284add-86d1-6d10-b4e0-30ac094f8af1

The unique identifier of the Z side port.

zSideVlanCTag integer 5 The C Tag of the Z side port.
zSideVlanSTag integer 8 The S Tag of the Z side port.
isFirstPage boolean

true

false

Indicates whether the page being displayed is the first page.
isLastPage boolean

true

false

Indicates whether the page being displayed is the last page.
pageNumber integer 20 The page number of the page which is currently being displayed. 
totalCount integer 450 The number of items returned as the response for the API request.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET L2 Buyer connections

GET l2/buyer/connections

 Method  GET
 URL or End Point  /ne/v1/l2/buyer/connections
 Headers  Authorization, Content-Type
 Query Parameters  status, metroCode, buyerPortName, buyerPortUUID, searchtType, subAccount, pageNumber, pageSize
 Body  Not applicable

 

This API returns all outgoing connections of the 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 Started section.

 

The following screenshots show a sample curl request to obtain all outgoing L2 connections for user credentials submitted and its JSON response. 

 

curl -X

GET "https://api.equinix.com/ne/v1/l2/buyer/connections?metroCode=DC"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
status No array[string] PROVISIONED

"PROVISIONED"

"DEPROVISIONED"

"PENDING_APPROVAL"

Indicates the status of the connection at Equinix's end (A Side).
metroCode No string DC

 

The 2 character metro code of the metro for which to retrieve service profiles. It can be a single code (&metroCode=Dc) or an array of codes (&metroCode=Dc&metroCode=Sv). 
buyerPortName No string JohnDoePort   The name of the buyer port.
buyerPortUUID No string 006d08e2-788e-4c83-82d3-07b1787644a5   The unique identifier of the buyer port.
sellerPortName No string JohnDoe2Port   The name of the seller port.
searchType No string AND

"AND"

"OR"

Querying operations.
subAccount No string 456   Can only be used by resellers.
pageNumber No integer 1   The page number of the page which is currently being displayed. 
pageSize No integer 20   The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 

 

Sample response:

 

{
    "isFirstPage": true,
    "totalCount": 467,
    "isLastPage": false,
    "pageSize": 20,
    "content": [
        {
            "buyerOrganizationName": "JOHN-DOE-ORG",
            "uuid": "006d08e2-788e-4c83-82d3-07b1787644a5",
            "name": "SAL-AZURE-TR-SEC-20",
            "vlanSTag": 200,
            "portUUID": "66284add-86d1-6d10-b4e0-30ac094f8af1",
            "portName": "JOHN DOE TEST",
            "asideEncapsulation": "dot1q",
            "metroCode": "TR",
            "metroDescription": "Toronto",
            "providerStatus": "DEPROVISIONED",
            "status": "DEPROVISIONED",
            "billingTier": "Up to 50 MB",
            "authorizationKey": "99973578-36f9-47f8-b12f-afa3faf02d06",
            "speed": 50,
            "speedUnit": "MB",
            "redundancyType": "secondary",
            "redundancyGroup": "28c02121-f093-4340-90c9-081b17b239c8",
            "sellerMetroCode": "TR",
            "sellerMetroDescription": "Toronto",
            "sellerServiceName": "Azure Express Route",

            "sellerServiceUUID": "a1390b22-bbe0-4e93-ad37-85beef9d254d",
            "sellerOrganizationName": "John Doe Org",
            "notifications": [
                "JohnDoe@equinix.com"
            ],

            "namedTag": "Private",
            "createdDate": "2018-08-30T04:20:36.033Z",
            "createdBy": "JohnDoe@equinix.com",
            "createdByFullName": "JohnDoe",
            "createdByEmail": "JohnDoe@equinix.com",
            "lastUpdatedDate": "2018-09-14T02:21:06.425Z",
            "deletedBy": "JohnDoe@equinix.com",
            "deletedDate": "2018-09-02T16:03:36.349Z",
            "deletedByEmail": "JohnDoe@equinix.com",
            "zSidePortName": "John-Port",
            "zSidePortUUID": "6f5680ea-1513-5130-50e0-30ac094f83ec",
            "zSideVlanSTag": 8,
            "remote": false,
            "private": false,
            "self": false

        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content object   An array containing the response data.
asideEncapsulation string

"Dot1q"

"Qinq"

The encapsulation of the buyer port (Dot1q or QinQ).
authorizationKey string 99973578-36f9-47f8-b12f-afa3faf02d06 The authorization key to be used by the user/customer when creating connections to this profile.
billingTier string Up to 50 MB Billing tier for connection.
buyerOrganizationName string JOHN-DOE-ORG Buyer organization name.
createdBy string JohnDoe@equinix.com The username who created the connection.
createdByEmail string JohnDoe@equinix.com The email ID of the user who created the connection.
createdByFullName string JohnDoe The full name of the user who created the connection.
createdDate string 2018-08-30T04:20:36.033Z The date on which the connection was created.
lastUpdatedBy string   The username who updated the connection.
lastUpdatedDate string   The date on which the connection was last updated.
lastUpdatedByEmail string   The email ID of the user who updated the connection.
lastUpdatedByFullName string   The full name of the user who updated the connection.
namedTag string Private The type of peering you would like to set up with Azure Express Route.
notification array   Email address of the contact to be notified for any updates on the connection.
metroCode string TR The metro code denoting the source metro from where the connection has been created. 
metroDescription string   The metro name where connections to this service profile can be created. 
name string   Name of the connection.
namedTag string

Private

Public

Microsoft 

Manual

The type of peering for Azure Express Route.
portName string JOHN DOE TEST The name assigned to the port.
portUUID string 66284add-86d1-6d10-b4e0-30ac094f8af1 The unique identifier of the port.
private boolean

true

false

Indicates whether or not this is a private profile. If private, it can only be available for creating connections if correct permissions are granted (i.e. not public like AWS/Azure/Oracle/Google, etc.)
purchaseOrderNumber string   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
redundancyGroup string 28c02121-f093-4340-90c9-081b17b239c8 Grouping of a primary and secondary connection using a unique ID.
redundancyType string secondary The type of connection.
remote boolean

true

false

Indicates whether the connection is a remote connection.  (i.e. if the seller and buyer metros are different then it's a remote connection)
self boolean

true

false

Indicates whether the connection belongs to your organization. (i.e. source and destination belongs to your organization)
sellerMetroCode string TR The metro code denoting the destination metro where the connection has been created to. 
sellerMetroDescription string Toronto The metro name indicating the destination metro where the connection has been created to. 
sellerOrganizationName string John Doe Org Seller organization name associated with the connection.
sellerServiceName string Azure Express Route Seller service associated with the connection.
sellerServiceUUID string a1390b22-bbe0-4e93-ad37-85beef9d254d Seller service ID associated with the connection.
speed integer 50 Bandwidth speed
speedUnit string MB The unit of bandwidth speed.
providerStatus string

"DEPROVISIONED"

"PROVISIONED"

"PENDING_APPROVAL"

"NOT_AVAILABLE"

"DEPROVISIONING"

"PROVISIONING"

"FAILED"

"PENDING_BGP"

"AVAILABLE"

"OUTOFBANDWIDTH"

"ERROR"

The status of the connection at the service provider's end.
status string

DEPROVISIONED

PROVISIONED

The status of the connection at Equinix's end.
uuid string 006d08e2-788e-4c83-82d3-07b1787644a5 The unique identifier of the connection.
vlanSTag string 4 Stag name of the connection.
zSidePortName string John-Port

The name of the Z side port.

zSidePortUUID string 6f5680ea-1513-5130-50e0-30ac094f83ec

The unique identifier of the Z side port.

zSideVlanCTag integer 5 The C Tag of the Z side port.
zSideVlanSTag integer 8 The S Tag of the Z side port.
isFirstPage boolean

true

false

Indicates whether the page being displayed is the first page.
isLastPage boolean

true

false

Indicates whether the page being displayed is the last page.
pageNumber integer 20 The page number of the page which is currently being displayed. 
totalCount integer 467 The number of items returned as the response for the API request.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Network Edge Portal access.

 


body: 

DELETE Connections {uuid}

DELETE /ne/v1/l2/connections/{uuid}

 Method  DELETE
 URL or End Point  /ne/v1/l2/connections/{uuid}
 Headers  Authorization, Content-Type
 Query Parameter  NA
 Path Parameter  Unique Id of the connection
 Body   NA

 

Deletes a connection by its unique ID. 

 

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

 

The following screenshots show a sample curl request and its respective JSON response to delete a connection. 

 

curl -X

DELETE "https://api.equinix.com/ne/v1/l2/connections/5f888d91-d2c5-45bb-9b51-fed99f57f0ac"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Path Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string 5f888d91-d2c5-45bb-9b51-fed99f57f0ac   Unique Id of the connection.

 

Sample response: 

 

{
    "message": "deleted connection successfully",
    "primaryConnectionId": "6f422679-746e-4d94-b338-2a90370a7fe7"
}

 

The description of the response is as follows:

 

Field Name Type Example Values Description
message string deleted connection successfully The connection was deleted successfully.
primaryConnectionId string 6f422679-746e-4d94-b338-2a90370a7fe7 Connection Id of the deleted connection.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

GET agreement status

GET /ne/v1/device/agreement/account

 Method  GET
 URL or End Point  /ne/v1/device/agreement/account
 Headers  Authorization, Content-Type
 Query Parameters  account_number
 Body  Not applicable

 

Call this API to find out the status of your agreement, whether it is valid or not, or to just read the agreement terms. 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

A sample curl request:

 

curl -X

GET "https://api.equinix.com/ne/v1/device/agreement/account?account_number=2252619"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Query Parameter Name Mandatory Type Example Applicable Values Description
account_number Yes string 2252619   Customer's account number.

 

Sample response:

 

{
    "termsVersionID": "",
    "terms": "",
    "isValid": "true",
    "errorMessage": ""
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
termsVersionID string a2Z34000002CXRtEAO Version Id of the agreement. You will only see a version ID if you have not signed an agreement or your agreement is not valid anymore.  
terms string EQUINIX NETWORK EDGE SERVICES TRIAL AGREEMENT\r\n\r\nThis Equinix Network Edge Services Trial Agreement (this “Agreement”) is made and entered into by and between Equinix, Inc. (“Equinix,” “Us” or “We”) and you, our customer (“Customer”).  The terms of the agreement. You will only get the terms if you have not signed an agreement or the agreement is not valid anymore.
isValid string

True

True if the agreement is valid, false if it is not.
errorMessage string   Error message.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

POST agreement

POST /ne/v1/device/agreement/account

 Method  POST
 URL or End Point  /ne/v1/device/agreement/account
 Headers  Authorization, Content-Type
 Path Parameters  NA
 Body Parameters  accountNumber, apttusId

 

Call this API to post an agreement. 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.

 

curl -X

POST "https://api.equinix.com/ne/v1/device/agreement/account"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d "{
"accountNumber": "V74191621",

"apttusId": "a2Z34000002CXRtEAO"

}"

 

The description of the body parameters is as follows:

 

Parameter Name Mandatory Type Example Applicable Values Description
accountNumber Yes string 8907778

 

Customer's account number.
apttusId Yes string a2Z34000002CXRtEAO   Version number of the agreement.

 

{
    "status": "PROCESSED"
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
status string PROCESSED The agreement request is being processed.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET BGP {bgpuuid}

GET /ne/v1/services/bgp/{bgpuuid}

 Method  GET
 URL or End Point  /ne/v1/services/bgp/{bgpuuid}
 Headers  Authorization, Content-Type
 Path Parameters  bgpUUID
 Body  Not applicable

 

This API returns BGP configuration for a bgpUUID. 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 screenshot shows a sample curl request to obtain BGP configuration for a uuid.  

 

curl -X

GET "https://api.equinix.com/ne/v1/services/bgp/7ef81cbe-01ed-4c27-8b2f-69d3a3fd4d6a"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the path parameter is as follows:

 

Path Parameter Name Mandatory Type Example Applicable Values Description
bgpuuid Yes string 7ef81cbe-01ed-4c27-8b2f-69d3a3fd4d6a   Unique Id of the BGP peering.

 

Sample response:

 

{
    "uuid": "6ea5a0e4-2bf7-45c2-9aa7-e846a8cd5567",
    "connectionUUID": "e5f30fc6-ae9d-4fbb-8020-d61329d8fe34",
    "virtualDeviceUUID": "f61e75d2-2008-43f4-bfee-1dd17b1e1a28",
    "localIpAddress": "12.0.0.1/30",
    "localAsn": 10061,
    "remoteAsn": 10050,
    "remoteIpAddress": "12.0.0.2",
    "state": "Idle",
    "createdBy": "nfv-sit1",
    "createdByFullName": "nfv-sit1 nfv-sit1",
    "createdDate": "2019-05-20T22:30:18.244Z",
    "createdByEmail": "test@equinix.com",
    "provisioningStatus": "PROVISIONED"
}

 

The description of the response payload is as follows:

 

Field Type Example Values

Description

 

uuid string 6ea5a0e4-2bf7-45c2-9aa7-e846a8cd5567 Unique Id of BGP peering. 
connectionUUID string e5f30fc6-ae9d-4fbb-8020-d61329d8fe34 Unique Id of the connection between your virtual device and another service provider.
virtualDeviceUUID string

f61e75d2-2008-43f4-bfee-1dd17b1e1a28

Unique Id of your virtual device.
localIpAddress string 12.0.0.1/30 Local IP Address. This is the IP address of the virtual device in CIDR format.
localAsn string 10061 Local ASN (autonomous system number). This is the ASN of your virtual device. 
remoteIpAddress string 12.0.0.2 Remote IP address. This is the IP address of the cloud service provider.
remoteAsn string 10013 Remote ASN (autonomous system number). This is the ASN of the cloud service provider. 
state string Idle State of the BGP peering. One of Idle, Connect, Active, Established, OpenSent, and OpenConfirm.
createdBy string nfv-sit1 The username of the user who created the connection.
createdDate string 2018-08-30T04:20:36.033Z The date on which the connection was created.
createdByFullName string nfv-sit1 nfv-sit1 Full name of the user who created BGP peering.
createdByEmail string test@equinix.com Created by email.
provisioningStatus string PROVISIONED Provisioning status of BGP peering. One of PROVISIONING, PROVISIONED, or FAILED.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Network Edge Portal access.

 


body: 

GET BGP configuration {connUUID}

GET /ne/v1/services/bgp/connection/{connectionUUID}

 Method  GET
 URL or End Point  /ne/v1/services/bgp/connection/{connectionUUID}
 Headers  Authorization token, Content-Type
 Path Parameters  connectionUUID
 Body  Not applicable

 

This API returns BGP configuration for a connection (connectionUUID). 

 

To obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

A sample curl request to obtain BGP configuration for a connection.  

 

curl -X

GET "https://api.equinix.com/ne/v1/services/bgp/connection/7ef81cbe-01ed-4c27-8b2f-69d3a3fd4d6a"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the path parameter is as follows:

 

Path Parameter Name Mandatory Type Example Applicable Values Description
connectionUUID Yes string 7ef81cbe-01ed-4c27-8b2f-69d3a3fd4d6a   Unique Id of the connection.

 

Sample response:

 

{
    "uuid": "6ea5a0e4-2bf7-45c2-9aa7-e846a8cd5567",
    "connectionUUID": "e5f30fc6-ae9d-4fbb-8020-d61329d8fe34",
    "virtualDeviceUUID": "f61e75d2-2008-43f4-bfee-1dd17b1e1a28",
    "localIpAddress": "12.0.0.1/30",
    "localAsn": 10061,
    "remoteAsn": 10050,
    "remoteIpAddress": "12.0.0.2",
    "state": "Idle",
    "createdBy": "nfv-sit1",
    "createdByFullName": "nfv-sit1 nfv-sit1",
    "createdDate": "2019-05-20T22:30:18.244Z",
    "createdByEmail": "test@equinix.com",
    "provisioningStatus": "PROVISIONED"
}

 

The description of the response payload is as follows:

 

Field Type Example Values

Description

 

uuid string 6ea5a0e4-2bf7-45c2-9aa7-e846a8cd5567 Unique Id of BGP peering. 
connectionUUID string e5f30fc6-ae9d-4fbb-8020-d61329d8fe34 Unique Id of the connection between your virtual device and another service provider.
virtualDeviceUUID string

f61e75d2-2008-43f4-bfee-1dd17b1e1a28

Unique Id of your virtual device.
localIpAddress string 12.0.0.1/30 Local IP Address. This is the IP address of the virtual device in CIDR format.
localAsn string 10061 Local ASN (autonomous system number). This is the ASN of your virtual device. 
remoteIpAddress string 12.0.0.2 Remote IP address. This is the IP address of the cloud service provider.
remoteAsn string 10013 Remote ASN (autonomous system number). This is the ASN of the cloud service provider. 
state string   State of the BGP peering. One of Idle, Connect, Active, Established, OpenSent, and OpenConfirm.
createdBy string nfv-sit1 The username of the user who created the connection.
createdDate string 2018-08-30T04:20:36.033Z The date on which the connection was created.
createdByFullName string nfv-sit1 nfv-sit1 Full name of the user who created BGP peering.
createdByEmail string test@equinix.com Created by email.
provisioningStatus string PROVISIONED Provisioning status of BGP peering. One of PROVISIONING, PROVISIONED, or FAILED.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Network Edge Portal access.

 


body: 

GET VPNs

GET /ne/v1/services/vpn

 Method  GET
 URL or End Point  /ne/v1/services/vpn
 Headers  Authorization, Content-Type
 Query Parameters  statusList [], virtualDeviceUUID, pageNumber, pageSize
 Body  Not applicable

 

This API returns all VPNs. 

 

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

 

Sample curl request to get VPNs. 

 

curl -X

GET "https://api.equinix.com/ne/v1/services/vpn?pageNumber=0&pageSize=20"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Description of the query parameters:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
statusList No array[string] PROVISIONED

"PROVISIONED"

"PROVISIONING"

"FAILED"

"DEPROVISIONED"

"DEPROVISIONING"

List of VPN status.
virtualDeviceUUID No string 116b4f6a-bb12-45dc-b573-05dba39c6cb1   Unique Id of a virtual device.
pageNumber No integer 1   The page number. 
pageSize No integer 20   The number of items to be displayed per page. 

 

Sample response:

 

{
    "totalCount": 1,
    "pageNumber": 0,
    "pageSize": 20,
    "list": [
        {
            "configName": "rr1-apr22-nonha-vpn1",
            "peerIp": "10.10.10.2",
            "peerSharedKey": "cnIxLWFwcjIyLW5vbmhhLXZwbjE=",
            "remoteAsn": 234568,
            "remoteIpAddress": "10.10.10.30",
            "password": "welcome1",
            "localAsn": 234565,
            "tunnelIp": "212.14.101.1/24",
            "virtualDeviceUUID": "7815a65d-214d-412b-9c50-17237426177a",
            "siteName": "NoNHAvpn",
            "uuid": "b884d9c0-8771-49b2-800b-34701246aba1",
            "status": "DEPROVISIONED",
            "bgpState": "Idle",
            "tunnelStatus": "DOWN",
            "createdDate": "2019-04-23T02:48:45.097Z",
            "createdByFullName": "nfv-sit4 nfv-sit4",
            "createdByEmail": "test@equinix.com",
            "createdBy": "nfv-sit4",
            "lastUpdatedDate": "2019-04-24T01:50:23.376Z",
            "lastUpdatedByFullName": "nfv-sit4 nfv-sit4",
            "lastUpdatedByEmail": "test@equinix.com",
            "lastUpdatedBy": "nfv-sit4"
        }
]
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
totalCount integer 1 Total count.
pageNumber integer 1 Page number.
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
list array list[] An array containing VPN objects.
configName string test2 Description of the VPN. This is between 3 and 50 characters.
peerIp string 1.1.1.1 IP Address of the remote site to which you connect (this is on the customer side). 
peerSharedKey string 213 Pre-shared key for VPN
remoteAsn string 21345 Remote ASN (autonomous system number). 
remoteIpAddress string 1.1.1.1 Remote IP address to establish BGP peering (this is on the customer side)
password string abc123 Password for BGP peering.
localAsn string 12345 Local ASN (autonomous system number) of Equinix site. 
tunnelIp string 2.2.2.2/25 Local tunnel IP in CIDR format
virtualDeviceUUID string 7d12f7c6-c9ee-4a14-9b00-5873eadf7708 Unique Id of the virtual device.
siteName string testVPN Your remote siteName. 
uuid string d93fad3f-dbe6-440d-ba94-8312e831d57a Unique Id of the VPN
status string PROVISIONED VPN status. One of Provisioning, Provisioned, Failed, Deprovisioning, or Deprovisioned.
bgpState string Idle BGP state. One of Idle, Connect, Active, Established, OpenSent, or OpenConfirm.
tunnelStatus string DOWN Tunnel status. Either Up or Down.
createdDate string   2019-04-23T02:48:45.097Z
createdByFullName string nfv-sit4 nfv-sit4 Created by (full name).
createdByEmail string test@equinix.com Created by (email).
createdBy string nfv-sit4 Created by (username).
lastUpdatedDate string 2019-04-24T01:50:23.376Z Last update date.
lastUpdatedByFullName string nfv-sit4 nfv-sit4 Last updated by (full name).
lastUpdatedByEmail string test@equinix.com Last updated by (email).
lastUpdatedBy string nfv-sit4 Last updated by (username).

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Network Edge Portal access.

 


body: 

DELETE VPN configuration by UUID

DELETE /ne/v1/services/vpn/{uuid}

 Method  DELETE
 URL or End Point  /ne/v1/services/vpn/{uuid}
 Headers  Authorization, Content-Type
 Query Parameter  NA
 Path Parameter  Unique Id of the VPN configuration
 Body   NA

 

Deletes a VPN configuration by its unique ID. 

 

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

 

The following screenshots show a sample curl request and its respective JSON response to delete a VPN configuration. 

 

curl -X

DELETE "https://api.equinix.com/ne/v1/services/vpn/5f888d91-d2c5-45bb-9b51-fed99f57f0ac"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Path Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string 5f888d91-d2c5-45bb-9b51-fed99f57f0ac   Unique Id of the VPN configuration.

 

Sample response: 

 

202 : Deletion request accepted.

 

The description of the response is as follows:

 

HTTP status Description
202 Deletion request accepted.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Portal access.

 


body: 

Sample Code

 


body: 

Connect to cloud routing

    Connect a virtual device to AWS

 


body: 

Establish BGP peering

    Establish BGP Peering

 


body: 

Establish VPN connectivity

    Establish VPN connectivity

 


body: 

Launch virtual devices

    Launch CSR1000V Non-HA & HA devices

 


body: 

Status codes, Error codes & Troubleshooting tips

This section provides an overview of the common error codes as well as general guidance on how to troubleshoot and handle errors.

 


body: 

HTTP Status codes


body: 

200: Success

The 200 (Success) status code indicates that the HTTP request was successful. In a GET request, the response will contain an entity corresponding to the requested resource whereas, in a POST request, the response will contain an entity describing or containing the result of the action.

 

Code 200
Description Success.

 

curl -X

GET "https://api.equinix.com/ne/v1/device/metro"

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 

This is an example of a success message.

 

{
    "totalCount": 3,
    "pageNumber": 1,
    "pageSize": 20,
    "content": [
        {
            "region": "AMER",
            "metroCode": "DC",
            "metroDescription": "Ashburn"
        },
        {
            "region": "EMEA",
            "metroCode": "LD",
            "metroDescription": "London"
        },
        {
            "region": "AMER",
            "metroCode": "SV",
            "metroDescription": "Silicon Valley"
        }
    ]
}

 


body: 

400: Bad Request

The 400 (Bad request) status code indicates that server cannot process the request due to something that is perceived to be a client error (e.g. malformed request syntax, invalid request message framing, or deceptive request routing).

 

Code 400
Description Validation Error.
Generic Cause Malformed request due to field or business validation.
Quick Fix Ensure the payload sent adheres to the parameter requirements.

 

There are different types of Validation errors and this section provides sample scenarios with validation errors as well as tips on how to identify them.

 


body: 

IC-NFV-CON-06

Code IC-NFV-CON-06
Description Invalid request.
Generic Cause Incorrect virtual device ID has been passed.
Quick Fix Verify the virtual device ID passed.

 

    Error scenario example

ERROR   

CODE:       "IC-NFV-CON-06"
MESSAGE:    "Primary Virtual Device not found."

PROPERTY:   ""

MOREINFO:   "We can't find that Virtual Device."

 

Verify the virtual device ID  passed.

 

curl 

The virtual device ID is incorrect. Replace the ID with the correct ID.

POST "https://api.equinix.com/ne/v1/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "virtualDeviceUUID": "6c2845e5-be63-4261-ba1c-a53a7e4cf5ec", 

  "primaryName": "JohnDoePrimary",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "secondaryName": "JohnDoeSecondary",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
    "notifications": [
    "JohnDoe@equinix.com"
  ]

}'

 


body: 

IC-LAYER2-AUTH-006

Code IC - LAYER2 - AUTH - 006
Description Invalid request.
Generic Cause The given named tag has already been used in another connection.
Quick Fix Verify whether there is an existing connection with the given NamedTag associated with the given authorization/service key.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-AUTH-006"
MESSAGE:    "Error while validating Authorization Key, NamedTag already in use"

MOREINFO:   ""
PROPERTY:   "authorizationkey"

 

Verify the namedTag and modify the value as shown below.

 

curl -X

GET "https://api.equinix.com/ne/v1/l2/connections" 

Rename the namedTag to another value such as "Public", "Microsoft", or "Manual".

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI" 

-d '{

  "primaryName": "johnDoePrimary",

  "profileUUID": "274afb42-6d3a-4114-8f7e-717efee792ae",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "879324",
  "virtualDeviceUUID": "ecb215dc-0d1d-4a48-a150-aacad8d3a371",
  "secondaryName": "johnDoeSecondary",
  "secondaryVirtualDeviceUUID": "03c2cfef-0ec2-4599-81c9-09efa0d7b0e7",
  "secondarySpeed": 50,
  "secondarySpeedUnit": "MB",
  "namedTag": "Private",
  "sellerMetroCode": "DC",
  "authorizationKey": "fbc3c0e1-59e7-4bfe-b5f3-209dee6b692a"
}'

 

 


body: 

401: Unauthorized

The 401 (Unauthorized) status code indicates that the authentication credentials received are not authorized. The user may repeat the request with a new or replaced Authorization header field. 

 

Code 401
Description Authentication Error.
Generic Cause Unauthorized authentication token.
Quick Fix Verify whether an authentication token is obtained and ensure to provide this with each request.

 

There are different types of Authentication errors and this section provides sample scenarios of authentication errors as well as tips on how to identify them.

 


body: 

403: Forbidden

The 403 (Forbidden) status code indicates that you do not have the necessary privilege to access the resource.

 

Code 403
Description Forbidden resource.
Generic Cause You do not have the necessary privilege to access the resource.
Quick Fix Verify end-point URL and resource info.

 

 


body: 

404: Resource not found 

The 404 (Resource not found) status code indicates that the server cannot find the requested resource but may be available in the future.

 

Code 404
Description Resource not found.
Generic Cause Resource is invalid or unavailable.
Quick Fix Verify end-point URL and resource info.

 

 


body: 

IC-NFV-VD-003

Code IC-NFV-VD-003
Description Virtual device not found
Generic Cause You have provided an incorrect UUID (unique Id) of the virtual device.
Quick Fix Verify the UUID (unique Id) of the virtual device.

 

   Error scenario example

ERROR   

CODE:       "IC-NFV-VD-003"
MESSAGE:    "Virtual device not found"

PATH        "/ne/v1/device/virtualdevice/d155c656-86da-4beb-b37e-dc91fd5c20"

TIMESTAMP   "1544951546619"

 

Verify UUID (unique Id of the virtual device).

 

The unique Id of the virtual device is not correct.

curl -X
GET "https://api.equinix.com/ne/v1/device/virtualdevice/d155c656-86da-4beb-b37e-dc91fd5c20"

-H "accept: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 


body: 

415: Unsupported media type 

The 415 (Unsupported media type) status code indicates that the request has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.

 

 

Code 415
Description Unsupported media type.
Generic Cause Server is refusing to service the request because the payload is in a format not supported by this method on the target resource.
Quick Fix Verify request payload.

 


body: 

429: Too many request Error

The 429 (Too many requests) status code indicates that the user has sent too many requests in a given amount of time.

 

Code 429
Description Internal server error.
Generic Cause Request rejected due to rate limiting (number of requests exceeded for the given time).
Quick Fix Try again later or post the issue on our forum or contact api-support@equinix.com .

 


body: 

500: Internal Server Error 

The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

 

Code 500
Description Internal server error.
Generic Cause System encountered an unexpected problem and is being tracked.
Quick Fix Try again or or post the issue on our forum or contact api-support@equinix.com.

 


body: 

503: Service unavailable

The 503 (Service unavailable) status code indicates that the server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

 

Code 503
Description Service unavailable.
Generic Cause Service unavailable due to temporary overload or scheduled maintenance and is likely be alleviated after some delay.
Quick Fix Try again or post the issue on our forum or contact api-support@equinix.com.
 

 


body: 

Don't Like Reading?


body: 

How about a 1-minute video? 

Connecting to Oracle Fast Connect

 

 

Calling OAuth API

 

 


body: 

Take a shot at our forum

Network Edge Forum

 


body: 

Glossary

 

Access Token

A credential used to communicate with the API

Cage

A custom build (as per customer’s requirement) and secured mesh enclosure to house multiple cabinets in it.

IBX

Equinix International Business Exchange

OAuth

 

OAuth (Open Authorization) is an open standard for token-based authentication and authorization on the Internet.

 

Rack

A physical enclosure to hold IT equipment, also called a Cabinet.

 

Refresh Token

 

A token that contains the information required to obtain a new Access Token.

 

 


body: 

Style guide and References

Additional information

 

 

Tips and recommendation 

 

 

Critical information 

 

 

Code snippet

 

 

Output snippet 

 

 

Error information

 

 

Internal Links

 

External Links

 

References Links
AWS AWS icons
Azure Azure logo
Google Google icons    Google logo
Oracle Oracle logo

 


body: 

 

 

 Contact us

If you have any questions or comments regarding Equinix APIs, please contact api-support@equinix.com


Twitter Feed

About Equinix

Equinix connects the world's leading businesses to their customers, employees and partners inside the world's most connected data centers in 44 markets across five continents. In the United States, Equinix operates data centers in Atlanta, Boston, Chicago, Dallas, Denver, Los Angeles, Miami, New York, Philadelphia, Seattle, Silicon Valley and Washington D.C.

Developer Platform - Key Highlights

  • Explore, Subscribe & Connect to Equinix API Ecosystem​
  • Test Drive Equinix APIs using our Playground
  • Start your journey with Getting Started Guide

Recent News