Skip to main content
Index

Connect to Enterprises

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 Fabric Portal. 

Layer 2 redundant enterprise connection

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 the 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 Fabric, contact your local Equinix Service Desk. 

Step 2: Get Attribute Information

2a) Get Port

Retrieve your allocated Equinix Fabric port information.

 

Refer to GET Port under the API Reference section for instructions on how to retrieve port details. You may skip this step if you already know your port information.

 

2b) Get Metros

Find all metros where Equinix Fabric is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your connection.

 

Refer to GET Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know this information.

 

2c) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

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 Equinix Fabric portal.

For more information please refer to the Equinix Fabric documentation at https://docs.equinix.com/en-us/Content/Interconnection/ECXF/landing-pages/ECXF-landing-main.htm

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in Equinix Fabric. You may skip this step if you already know the service profile details.

Step 3: Create Connection

POST /ecx/v3/l2/connections

Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, secondaryName, secondaryPortUUID, secondaryVlanSTag, secondaryVlanCTag, primaryZSideVlanCTag, secondaryZSideVlanCTag

 

The POST connections API creates a layer 2 connection between your port 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 token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create layer 2 redundant enterprise connection using  Dot1q and QinQ ports and a sample JSON response for this API. 

 

Should you want to estimate the price of this connection, use the API GET Prices.

 

Redundant Connection from a Dot1Q port to a service profile with a Dot1Q port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_Dot1Q",

  "profileUUID": "7a73af1a-3d74-47ac-b778-6bf455d1174e",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "4f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "873",

  "secondaryName": "JohnDoe_Dot1Q_To_Dot1Q_2",

  "secondaryVlanSTag": "873",

  "secondaryPortUUID": "7g831d3b-9740-7420-bae0-30ac1885127a",

  "sellerMetroCode": "SV"

}

 

Redundant Connection from a Dot1Q port to a service profile with a QinQ port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_QinQ",

  "profileUUID": "31b7263f-7e6a-42d0-859e-80a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "335",

  "secondaryName": "JohnDoe_Dot1Q_To_QinQ_2",

  "secondaryVlanSTag": "335",

  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",

  "sellerRegion": "us-sv",

  "sellerMetroCode": "SV",

  "primaryZSideVlanCTag": "421",

  "secondaryZSideVlanCTag": "521"

}

 

Redundant Connection from a QinQ port to a service profile with a Dot1Q port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_QinQ_To_Dot1Q",

  "profileUUID": "2a73af1a-3c74-47ac-b778-6bf455d1174e",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "6f891d3b-972d-73d0-bae3-30ac1995197a",

  "primaryVlanSTag": "771",

  "primaryVlanCTag": "117",

  "secondaryName": "JohnDoe_QinQ_To_Dot1Q2",

  "secondaryPortUUID": "7f892d5b-993f-73f0-bae0-32ad1889197a",

  "secondaryVlanSTag": "881",

  "secondaryVlanCTag": "118",

  "sellerMetroCode": "SV"

}

 

Redundant Connection from a QinQ port to a service profile with a QinQ port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

{

  "primaryName": "JohnDoe_QinQ_To_QinQ",

  "profileUUID": "32b7273f-7e7a-43d0-859e-81a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-96d3-6d30-bae0-30ac1885197a",

  "primaryVlanSTag": "499",

  "secondaryName": "JohnDoe_QinQ_To_QinQ2",

  "secondaryVlanSTag": "2456",

  "secondaryPortUUID": "7f21d3b-93d3-6d30-cae0-33ac2895297a",

  "sellerRegion": "us-sv",

  "sellerMetroCode": "SE"

}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoe_Dot1Q_To_Dot1Q  

User-defined name of the primary connection.

 

Supply an alpha-numeric string, which can include hyphens and underscores ('-' & '_') as special characters (no other special characters are allowed).

 

Max Length: 24 characters

primaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique Equinix-assigned ID of the buyer's primary port from where the connection originates.
primaryVlanSTag Yes integer 640

 

S-Tag/Outer-Tag of the primary connection.

 

Range: 2 - 4094.

primaryVlanCTag Yes string 641  

C-Tag/Inner-Tag of the primary connection.

 

Range: 2 - 4094

profileUUID Yes string 84c6616c-573a-447d-a478-9fab8fff284d   Unique Equinix-assigned ID of the provider's service profile.
speed Yes integer 50  

Speed/bandwidth to be allocated to the connection.

speedUnit Yes string MB  

Unit of the speed/bandwidth to be allocated to the connection.

 

Values: Either MB or GB.

notifications Yes array  johnDoe@example.com

 

A list of email addresses that are notified when there are any updates on this connection.

 

Example:
["user@example.com", "user2@example.com"]

purchaseOrderNumber No string 123456789   This optional field links the purchase order to the connection on Equinix. This link is reflected on the invoice.
authorizationKey No string     An optional field, the value of which is based on the service profile to which you want to connect.  
sellerMetroCode Yes string DC  

The metro code that denotes the connection’s destination (Z side). 

 

If sellerMetroCode is empty, the value defaults to the metro code of the port. 

sellerRegion No string us-sv   An optional field that needs to be passed if requested by the service profile. It indicates the region in which the seller port resides.
secondaryName Yes string JohnDoe_QinQ_To_QinQ2  

Name of the secondary connection.

 

Supply an alpha-numeric string, which can include hyphens and underscores ('-' & '_') as special characters (no other special characters are allowed).

 

Max Length: 24 characters

secondaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique ID of the buyer's secondary port from which the secondary connection would originate.
secondaryVlanSTag Yes string 442  

S-Tag/Outer-Tag of the secondary connection.

 

Range: 2 - 4094

secondaryVlanCTag Yes string 542  

C-Tag/Inner-Tag of the secondary connection.

 

Range: 2 - 4094

primaryZSideVlanCTag Yes string 558  

C-Tag/Inner-Tag of the primary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual").

 

Range: 2 - 4094

secondaryZSideVlanCTag Yes string 542  

C-Tag/Inner-Tag of the secondary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual").

 

Range: 2 - 4094

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to a seller/service profile (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) Vlan S-tag required Vlan C-tag required ZSide Vlan C-tag required Port Type ( Z-side)
Dot1Q port Yes No Yes QinQ port
Dot1Q port Yes No No Dot1Q port
QinQ port Yes Yes No Dot1Q port
QinQ port Yes No No QinQ port

 

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

 

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

    "secondaryConnectionId": "888d4c1-5444-4511-b2e4-51f06f062974"
}

 

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 888d4c1-5444-4511-b2e4-51f06f062974 Indicates the secondary connection ID.

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API GET Connections{uuid}

 

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{uuid}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status at the enterprise's end.

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_APPROVAL NOT_AVAILABLE Connection request has been sent to seller and is awaiting 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 DELETE Connections{uuid} the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_DELETE AVAILABLE Deletion request has been sent to seller and is awaiting 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.

Layer 2 non-redundant enterprise connection

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 the 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 Fabric, contact your local Equinix Service Desk. 

Step 2: Get Attribute Information

2a) Get Port

Retrieve your allocated Equinix Fabric port information.

 

Refer to GET Port under the API Reference section for instructions on how to retrieve port details. You may skip this step if you already know your port information.

 

2b) Get Metros

Find all metros where Equinix Fabric is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your connection.

 

Refer to GET Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know this information.  

 

2c) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

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 Equinix Fabric portal.

For more information please refer to the Equinix Fabric documentation at https://docs.equinix.com/en-us/Content/Interconnection/ECXF/landing-pages/ECXF-landing-main.htm

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in Equinix Fabric. You may skip this step if you already know the service profile details.

Step 3: Create Connection

POST /ecx/v3/l2/connections

Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerMetroCode, primaryZSideVlanCTag

 

The POST connections API creates a layer 2 connection between your port 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 token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create layer 2 non-redundant enterprise connection using  Dot1q and QinQ ports and a sample JSON response for this API. 

 

Should you want to estimate the price of this connection, use the API GET Prices.

 

Non-Redundant Connection from a Dot1q port to a service profile with a Dot1q port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_Dot1Q",

  "profileUUID": "8e79b5e4-7c5b-4201-9334-fd89b37bec47",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "4f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "672",

  "sellerMetroCode": "DA"

}

 

Non-Redundant Connection from a Dot1q port to a service profile with a  QinQ port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_QinQ",

  "profileUUID": "31b7263f-7e6a-42d0-859e-80a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "335",

  "sellerMetroCode": "SV",

  "primaryZSideVlanCTag": "211",

}

 

Non-Redundant Connection from a QinQ port to a service profile with a Dot1q port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_QinQ_To_Dot1Q",

  "profileUUID": "2a73af1a-3c74-47ac-b778-6bf455d1174e",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "6f891d3b-972d-73d0-bae3-30ac1995197a",

  "primaryVlanSTag": "470",

  "primaryVlanCTag": "470",

  "sellerMetroCode": "DA"

}

 

Non-Redundant Connection from a QinQ port to a service profile with a QinQ port 

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

{

  "primaryName": "JohnDoe_QinQ_To_QinQ",

  "profileUUID": "32b7273f-7e7a-43d0-859e-81a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@example.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-96d3-6d30-bae0-30ac1885197a",

  "primaryVlanSTag": "470",

  "sellerMetroCode": "DA"

}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoe_AWS_QinQ  

User-defined name of the primary connection.

 

Supply an alpha-numeric string, which can include hyphens and underscores ('-' & '_') as special characters (no other special characters are allowed).

 

Max Length: 24 characters

primaryPortUUID Yes string 99991d3b-9750-7500-bae0-30ac1885197a   UUnique Equinix-assigned ID of the buyer's primary port from where the connection originates.
primaryVlanSTag Yes integer 774

 

S-Tag/Outer-Tag of the primary connection.

 

Range: 2 - 4094

primaryVlanCTag Yes string 775

 

C-Tag/Inner-Tag of the primary connection.

 

Range: 2 - 4094

profileUUID Yes string 999552b-39b0-49ea-a232-005088dc9c86   Unique Equinix-assigned ID of the provider's service profile.
speed Yes integer 50   Speed/bandwidth to be allocated to the connection.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.

 

Values: Either MB or GB.

notifications Yes array string JohnDoe@example.com

 

A list of email addresses that are notified when there are any updates on this connection.

 

Example:
["user@example.com", "user2@example.com"]

purchaseOrderNumber No string 0987654321   This optional field links the purchase order to the connection on Equinix. This link is reflected on the invoice.
authorizationKey No string     An optional field based on the service profile to which you want to connect. 
sellerMetroCode Yes string SV  

The metro code that denotes the connection’s destination (Z side). 

 

If sellerMetroCode is empty, the value defaults to the metro code of the port. 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to a seller/service profile (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) Vlan S-tag required Valan C-tag required ZSide Vlan C-tag required Port Type ( Z-side)
Dot1Q port Yes No Yes QinQ port
Dot1Q port Yes No No Dot1Q port
QinQ port Yes Yes No  Dot1Q port
QinQ port Yes No No QinQ port

 

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

 

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

 

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.
 

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API GET Connections{uuid}

Should you want to upgrade the speed/bandwidth of this connection, you can use the API PATCH Connections{uuid}.

 

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{uuid}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status at the enterprise's end.

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_APPROVAL NOT_AVAILABLE Connection request has been sent to seller and is awaiting 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 DELETE Connections{uuid} the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_DELETE AVAILABLE Deletion request has been sent to seller and is awaiting 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.