API - Connect to Microsoft Azure ExpressRoute

Establish a direct, layer 2 connection to Microsoft Azure to access the Azure Cloud Infrastructure and other Azure Cloud services.

note

This document covers creating a connection from a port, service token, or cloud router in the API. For information on creating a connection from a virtual device, including in the API, see Network Edge to Azure ExpressRoute

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 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 Azure ExpressRoute service profile information. More information on which service profile you should choose is on the Azure ExpressRoute Overview page.
- Azure ExpressRoute - a1390b22-bbe0-4e93-ad37-85beef9d254d
- Azure Government ExpressRoute - 0de4e413-edd7-4325-912f-7c8a4428e156
Identify and validate your ExpressRoute Service Key. Send a POST request to the /fabric/v4/connections/validate endpoint to verify that your ExpressRoute Service Key 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 Azure ExpressRouter, 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 Azure ExpressRoute details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the Azure ExpressRoute service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Set authenticationKey as your ExpressRoute Service Key .
Set peeringType as MICROSOFT or PRIVATE, depending on the services you are using the connection for. For more information, see Configuring Peering.
(Optional) Set linkProtocol.type to QINQ and specify a linkProtocol.vlanCTag. This sets the ExpressRoute VLAN ID used for peering. You can also set this value in the Azure portal after creating the connection.

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": "<your_port_uuid>"
      },
      "linkProtocol": {
        "type": "DOT1Q",
        "vlanTag": <vlan_id>
      }
    }
  },
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "DC"
      },
      "linkProtocol": {
        "type": "QINQ",
        "vlanCTag": <vlan_id>
      },
      "peeringType": "<peering_type>",
      "authenticationKey": "<expressroute_service_key>"
    }
  },
  "order": {
    "purchaseOrderNumber": "<purchase_order_number>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
        "<contact_email>"
      ]
    }
  ]
}

Connecting from a QINQ port

To create a connection from your DOT1Q port to Azure ExpressRouter, 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 QINQ
Provide the inner tag ID to linkProtocol.vlanCTag
Provide the outer tag ID to linkProtocol.vlanSTag

Provide your Azure ExpressRoute details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the Azure ExpressRoute service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Set authenticationKey as your ExpressRoute Service Key .
Set peeringType as MICROSOFT or PRIVATE, depending on the services you are using the connection for. For more information, see Configuring Peering.
(Optional) Set linkProtocol.type to QINQ and specify a linkProtocol.vlanCTag. This sets the ExpressRoute VLAN ID used for peering. You can also set this value in the Azure portal after creating the connection.

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": "<connection_name>",
  "bandwidth": <connection_speed>,
  "redundancy": {
    "priority": "<redundancy_code>"
  },
  "aSide": {
    "accessPoint": {
      "type": "COLO",
      "port": {
        "uuid": "<port_uuid>"
      },
      "linkProtocol": {
        "type": "QINQ",
        "vlanSTag": <vlan_id>,
        "vlanCTag": <vlan_id>
      }
    }
  },
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<metro_code>"
      },
      "authenticationKey": "<expressroute_service_key>"
    }
  },
  "order": {
    "purchaseOrderNumber": "<purchase_order_number>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
        "<contact_email>"
      ]
    }
  ]
}'

Connecting Using a Service Token

To create a connection from your DOT1Q port to Azure ExpressRouter, 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 Azure ExpressRoute details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the Azure ExpressRoute service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Set authenticationKey as your ExpressRoute Service Key .
Set peeringType as MICROSOFT or PRIVATE, depending on the services you are using the connection for. For more information, see Configuring Peering.
(Optional) Set linkProtocol.type to QINQ and specify a linkProtocol.vlanCTag. This sets the ExpressRoute VLAN ID used for peering. You can also set this value in the Azure portal after creating the connection.

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": "<connection_name>",
  "bandwidth": <connection_speed>,
  "redundancy": {
    "priority": "<redundancy_code>"
  },
  "aSide": {  
    "serviceToken": {  
      "uuid": "<your_aside_service_token>"  
    } 
  },
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<metro_code>"
      },
      "authenticationKey": "<expressroute_service_key>"
    }
  },
  "order": {
    "purchaseOrderNumber": "<purchase_order_number>"
  },
  "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 Azure ExpressRoute details and location details in the zSide object including:

Set accessPoint.type as SP.
Set profile.type as L2_PROFILE.
Specify the Azure ExpressRoute service profile you are connecting to in profile.uuid.
Specify the Equinix Metro location you are connecting to in location.metroCode.
Set authenticationKey as your ExpressRoute Service Key .
Set peeringType as MICROSOFT or PRIVATE, depending on the services you are using the connection for. For more information, see Configuring Peering.
(Optional) Set linkProtocol.type to QINQ and specify a linkProtocol.vlanCTag. This sets the ExpressRoute VLAN ID used for peering. You can also set this value in the Azure portal after creating the connection.

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.

curl -X  
POST 'https://api.equinix.com/fabric/v4/connections'  
-H 'content-type: application/json'  
-H 'authorization: Bearer <token>'  
-d '{
  "type": "IP_VC",
    "name": "<connection_name>",
  "bandwidth": <connection_speed>,
  "redundancy": {
    "priority": "<redundancy_code>"
  },
  "aSide": {
    "accessPoint": {
      "type": "CLOUD_ROUTER",
      "router": {
        "uuid": "<router_uuid>"
      }
    }
  },
  "zSide": {
    "accessPoint": {
      "type": "SP",
      "profile": {
        "type": "L2_PROFILE",
        "uuid": "<service_profile_uuid>"
      },
      "location": {
        "metroCode": "<metro_code>"
      },
      "authenticationKey": "<expressroute_service_key>"
    }
  },
  "order": {
    "purchaseOrderNumber": "<purchase_order_number>"
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
        "<contact_email>"
      ]
    }
  ]
}'

Monitoring the Connection Status

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

Equinix Connection States		Azure States
`equinixStatus` attribute values	`providerStatus` attribute values	Provider Status	Peerings Status	Description
`PROVISIONING`	`PROVISIONING`	Not provisioned	Not provisioned	Connection request has not been sent to Microsoft yet.
`PENDING_BGP_PEERING`	`PENDING_BGP`	Provisioned	Not provisioned	The connection has been approved and awaits for the customer to configure Microsoft peering on the Microsoft Azure portal. If you are connecting to Azure ExpressRoute from a Port, the status remains `PENDING_BGP_PEERING` until peering is completed in the Microsoft Azure portal and the status only changes to `PROVISIONED` once Equinix Fabric syncs with Microsoft. If you want to synchronize the BGP peering instantly, use Connection Actions API endpoint. If you are connecting to Azure ExpressRoute from a Fabric Cloud Router, you also need to configure your routing details for the connection in the Equinix Customer Portal.
`PROVISIONING`	`PROVISIONED`			Provisioning completed at Microsoft's end and the connection is provisioning at Equinix's end.
`PROVISIONED`	`PROVISIONED`			Connection established.

Prerequisites​

Connecting from a DOT1Q Port​

Connecting from a QINQ port​

Connecting Using a Service Token​

Connecting from a Fabric Cloud Router​

Monitoring the Connection Status​

Prerequisites

Connecting from a DOT1Q Port

Connecting from a QINQ port

Connecting Using a Service Token

Connecting from a Fabric Cloud Router

Monitoring the Connection Status