API - Connecting to AWS Direct Connect

Establish a direct, layer 2 connection between your IBX colocated assets and your Amazon Web Services (AWS) resources with Fabric and AWS Direct Connect. Use the API to create the connection from a Port, Network Edge device, or Fabric Cloud Router.

If you have an AWS-provided service token, see Connect to a Destination Using a Service Token.

API Prerequisites

Authenticate - Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication. Refer to API Authentication for instructions on how to call OAuth API to validate and authenticate your credentials.
Determine Your A-side Information. Either:
- Determine your Equinix Fabric ports information by sending a GET request to the /fabric/v4/ports endpoint. You need the port UUID(s) and the link protocol type (DOT1Q or QINQ),
OR
- Retrieve your a-side service token or tokens by sending a GET request to the /fabric/v4/serviceTokens endpoint. You need the token's UUID. The a-side token provides the relevant information to configure the a-side of the connection.
OR
- Determine your Network Edge device information. Check your available virtual devices and clusters by sending a GET request to the /ne/v1/devices endpoint. You need the device UUID(s). Send a GET request to the /ne/v1/devices/{device_id} endpoint to get the specifics of a device. You may choose any available interface on the device for your connection. If you do not specify one, the connection is automatically assigned to the next available interface.
OR
- Determine your Fabric Cloud Router information. Check your available cloud routers by sending a POST request to the /fabric/v4/routers/search endpoint. You need the router's UUID.
Identify the AWS Direct Connect service profile and location information. More information on which service profile you should choose is on the AWS Direct Connect Overview page.
- AWS Direct Connect UUID - 69ee618d-be52-468d-bc99-00566f2dd2b9
- AWS Direct Connect High Capacity UUID - de55ca94-df3b-4680-845f-6f7093f76bef
- AWS Direct Connect Redundant UUID - 8b5cbdbd-53da-4d37-9bfc-cc988eb522f1
- AWS Direct Connect- High Capacity Redundant - ed48616a-c182-40b4-a462-a78ba812e961
To find the location information, send a GET request to the /fabric/v4/serviceProfiles/{service_profile_ID} endpoint using one of the AWS Direct Connect service profile IDs. The metros object in the response contains a list of Equinix Metros and their associated AWS region. You need both to create a connection.
Identify and validate your Amazon Account ID. Log in to AWS Management Console and locate your account number. Refer to the AWS documentation for instructions on how to find your account number. Send a POST request to the /fabric/v4/connections/validate endpoint to verify that your AWS Account ID can be used to create a connection to the selected service profile in the given metro.

Connecting from a DOT1Q Port

To create a connection from your DOT1Q port to AWS, send a POST request to the /fabric/v4/connections endpoint. The connection type is EVPL_VC.

Provide your port information in the aSide object including:

accessPoint.type as COLO
Provide your port's UUID to port.uuid
linkProtocol.type as DOT1Q
Provide the VLAN ID to linkProtocol.vlanTag

Provide your AWS Direct Connect details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the AWS service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Specify the AWS region associated with the Equinix Metro in sellerRegion. This information can be found from the /fabric/v4/serviceProfiles/{service_profile_ID} endpoint. See API Prerequisites endpoint. See API Prerequisites for details.
Set authenticationKey as your AWS Account ID.

Specify any other connection configuration details, including bandwidth and redundancy, in the body of the request. For a full list of parameters and their descriptions, see the API Reference.

Sample cURL Request:

curl -X  
POST 'https://api.equinix.com/fabric/v4/connections'  
-H 'content-type: application/json'  
-H 'authorization: Bearer <token>'  
-d '{
  "type": "EVPL_VC",
  "name": "<your_connection_name>",
  "bandwidth": <connection_speed>,
  "redundancy": {
    "priority": "<redundancy_code>"
  },  
  "aSide": {  
    "accessPoint": {  
      "type": "COLO",  
      "port": {  
        "uuid": "<port_uuid>"  
      },  
      "linkProtocol": {  
        "type": "DOT1Q",  
        "vlanTag": <vlan_ID>  
      }  
    }  
  },  
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<equinix_metro_code>"
      },
      "sellerRegion": "<aws_region_name>",
      "authenticationKey": "<amazon_account_ID>"
    }
  },
  "project": {
    "projectId": "<project_uuid>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
      "<contact_email>"
      ]
    }
  ]
}'

Connecting from a QINQ Port

To create a connection from your QINQ port to AWS, send a POST request to the /fabric/v4/connections endpoint. The connection type is EVPL_VC.

Provide your port information in the aSide object including:

Set accessPoint.type as COLO
Provide your port's UUID to port.uuid
linkProtocol.type as QINQ
Provide the inner tag ID to linkProtocol.vlanCTag
Provide the outer tag ID to linkProtocol.vlanSTag

Provide your AWS Direct Connect details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the AWS service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Specify the AWS region associated with the Equinix Metro in sellerRegion. This information can be found from the /fabric/v4/serviceProfiles/{service_profile_ID} endpoint. See API Prerequisites endpoint. See API Prerequisites for details.
Set authenticationKey as your AWS Account ID.

Specify any other connection configuration details, including bandwidth and redundancy, in the body of the request. For a full list of parameters and their descriptions, see the API Reference.

Sample cURL Request:

curl -X  
POST 'https://api.equinix.com/fabric/v4/connections'  
-H 'content-type: application/json'  
-H 'authorization: Bearer <token>'  
-d '{  
  "type": "EVPL_VC",
  "name": "<your_connection_name>",
  "bandwidth": <connection_speed>,
  "redundancy": {
    "priority": "<redundancy_code>"
  }, 
  "aSide": {  
    "accessPoint": {  
      "type": "COLO",  
      "port": {  
        "uuid": "<port_uuid>"  
      },
      "linkProtocol": {  
        "type": "QINQ",  
        "vlanCTag": <inner_tag_ID>,  
        "vlanSTag": <outer_tag_ID>  
      } 
    } 
  },  
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<equinix_metro_code>"
      },
      "sellerRegion": "<aws_region_name>",
      "authenticationKey": "<amazon_account_ID>"
    }
  },
  "project": {
    "projectId": "<project_uuid>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
      "<contact_email>"
      ]
    }
  ]
}

Connecting Using a Service Token

To create a connection using an A-side Service Token to AWS, send a POST request to the /fabric/v4/connections endpoint. The connection type is EVPL_VC.

Provider your Service Token UUID to in the aSide object. The service token provides all other necessary information to establish the connection.

Provide your AWS Direct Connect details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the AWS service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Specify the AWS region associated with the Equinix Metro in sellerRegion. This information can be found from the /fabric/v4/serviceProfiles/{service_profile_ID} endpoint. See API Prerequisites endpoint. See API Prerequisites for details.
Set authenticationKey as your AWS Account ID.

Specify any other connection configuration details, including bandwidth and redundancy, in the body of the request. For a full list of parameters and their descriptions, see the API Reference.

Sample cURL Request:

curl -X  
POST 'https://api.equinix.com/fabric/v4/connections'  
-H 'content-type: application/json'  
-H 'authorization: Bearer <token>'  
-d '{  
  "type": "EVPL_VC",
  "name": "<your_connection_name>",
  "bandwidth": <connection_speed>,
  "redundancy": {
    "priority": "<redundancy_code>"
  }, 
  "aSide": {  
    "serviceToken": {  
      "uuid": "20d32a80-0d61-4333-bc03-707b591ae2f4"  
    } 
  },
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<equinix_metro_code>"
      },
      "sellerRegion": "<aws_region_name>",
      "authenticationKey": "<amazon_account_ID>"
    }
  },
  "project": {
    "projectId": "<project_uuid>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
      "<contact_email>"
      ]
    }
  ]
}

Connecting from a Network Edge Device

To create a connection from your Network Edge device to AWS, send a POST request to the /fabric/v4/connections endpoint. The connection type is EVPL_VC.

Define your Network Edge device in the aSide object including:

accessPoint.type as VD
virtualDevice.type as EDGE
virtualDevice.uuid as your device's UUID

Provide your AWS Direct Connect details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the AWS service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Specify the AWS region associated with the Equinix Metro in sellerRegion. This information can be found from the /fabric/v4/serviceProfiles/{service_profile_ID} endpoint. See API Prerequisites endpoint. See API Prerequisites for details.
Set authenticationKey as your AWS Account ID.

Specify any other connection configuration details, including bandwidth and redundancy, in the body of the request. For a full list of parameters and their descriptions, see the API Reference.

Sample cURL Request:

curl -X  
POST 'https://api.equinix.com/fabric/v4/connections'  
-H 'content-type: application/json'  
-H 'authorization: Bearer <token>'  
-d '{
  "type": "EVPL_VC",
  "name": "<your_connection_name>",
  "bandwidth": <connection_speed>,
  "redundancy": {
    "priority": "<redundancy_code>"
  },
  "aSide": {
    "accessPoint": {
      "type": "VD",
      "virtualDevice": {
        "type": "EDGE",
        "uuid": "<device_uuid>"
      }
    }   
  },
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<equinix_metro_code>"
      },
      "sellerRegion": "<aws_region_name>",
      "authenticationKey": "<amazon_account_ID>"
    }
  },
  "project": {
    "projectId": "<project_uuid>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
      "<contact_email>"
      ]
    }
  ]
}'

Connecting from a Fabric Cloud Router

To create a connection from your Network Edge device to AWS, send a POST request to the /fabric/v4/connections endpoint. The connection type is IP_VC.

Define your Fabric Cloud Router in the aSide object including:

Set accessPoint.type as CLOUD_ROUTER.
Set router.uuid as your router's UUID

Provide your AWS Direct Connect details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the AWS service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Specify the AWS region associated with the Equinix Metro in sellerRegion. This information can be found from the /fabric/v4/serviceProfiles/{service_profile_ID} endpoint. See API Prerequisites endpoint. See API Prerequisites for details.
Set authenticationKey as your AWS Account ID

Sample cURL Request:

curl -X  
POST 'https://api.equinix.com/fabric/v4/connections'  
-H 'content-type: application/json'  
-H 'authorization: Bearer <token>'  
-d '{
  "type": "IP_VC",
  "name": "<your_connection_name>",
    "bandwidth": <connection_speed>,
    "redundancy": {
      "priority": "<redundancy_code>"
    },
  "aSide": {
    "accessPoint": {
      "type": "CLOUD_ROUTER",
      "router": {
        "uuid": "<cloud_router_uuid>"
      }
    }
  },
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<equinix_metro_code>"
      },
      "sellerRegion": "<aws_region_name>",
      "authenticationKey": "<amazon_account_ID>"
    }
  },
  "project": {
    "projectId": "<project_uuid>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
      "<contact_email>"
      ]
    }
  ]
}'

Monitoring the Connection Status

Send a GET request to the fabric/v4/connections/{connection_id} endpoint to monitor connection status.

`equinixStatus` attribute values	`providerStatus` attribute values	AWS Direct Connect State	Description
`PROVISIONING`	`PROVISIONING`		Connection request has not been sent to AWS yet.
`PROVISIONED`	`PENDING_APPROVAL`	Ordering -> Requested	The connection awaits for acceptance.
`PROVISIONED`	`PROVISIONING`	Pending	Connection establishment in progress.
`PROVISIONED`	`PROVISIONED`	Pending -> Available	The connection has been accepted.

API Prerequisites​

Connecting from a DOT1Q Port​

Connecting from a QINQ Port​

Connecting Using a Service Token​

Connecting from a Network Edge Device​

Connecting from a Fabric Cloud Router​

Monitoring the Connection Status​

API Prerequisites

Connecting from a DOT1Q Port

Connecting from a QINQ Port

Connecting Using a Service Token

Connecting from a Network Edge Device

Connecting from a Fabric Cloud Router

Monitoring the Connection Status