Skip to main content

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.

Creating an ExpressRoute Circuit

In the Microsoft Azure portal, create an ExpressRoute circuit and retrieve its service key.

Refer to the Microsoft documentation for instructions on how to create an ExpressRoute circuit.

Fabric API Prerequisites

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

  2. Determine Your A-side Information. Either:

    • Retrieve your Equinix Fabric ports information using the Get All Ports API request.

    OR

    • Determine your Network Edge device information. You need a provisioned Equinix Virtual Device/Redundant Devices/Cluster with a registered license. Check your available virtual devices and clusters by calling Get Virtual Devices or Get Virtual Device {uuid}. You may choose any available interface on the device for your connection. However, Equinix will select an interface if you do not specify one.
  3. Choose the Z-side metro location. Use the Get All Metros API request to find all metros where Equinix Fabric is available and determine destination location.

  4. Identify the service profile. Use the Retrieve Service Profiles API request to search for a specific service profile or use the Get Service Profiles API request to list all available service profiles, and identify the profile you want to connect to.

  5. Validate your Authorization Key. Use the Validate Connection Authorization Key API request to verify that your Azure key can be used to create a connection to the selected service profile in the given metro.

Connecting to Microsoft Azure ExpressRoute from a DOT1Q Port

To create a connection from your DOT1Q port to Microsoft Azure ExpressRoute, send a POST request to the /fabric/v4/connections endpoint. Specify your connection's configuration details in the body of the request.

POST /fabric/v4/connections
MethodPOST
Endpoint/fabric/v4/connections
HeadersAuthorization, Content-Type
Path ParametersNot applicable
Query ParametersNot applicable
Body Parameterstype, name, order, bandwidth, redundancy, aSide, zSide, notifications

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": "Conn-1",
    "order": {
        "purchaseOrderNumber": "1-129105284100"
    },
    "bandwidth": 1000,
    "aSide": {
        "accessPoint": {
            "type": "COLO",
            "port": {
                "uuid": "a867f685-41b0-1b07-6de0-320a5c00abdd"
            },
            "linkProtocol": {
                "type": "DOT1Q",
                "vlanTag": 1001
            }
        }
    },
    "zSide": {
        "accessPoint": {
            "type": "SP",
            "profile": {
                "uuid": "20d32a80-0d61-4333-bc03-707b591ae2f5"
            },
            "location": {
                "metroCode": "SV"
            },
            "linkProtocol": {
                "type": "QINQ",
                "vlanCTag": 1001
            },
            "authenticationKey": "xx-xx-xx",
            "peeringType": "PRIVATE"
        }
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "test@equinix.com"
            ]
        }
    ]
}'

The parameters included in the request body are specific to this example. For a full list of parameters and their descriptions, see the API Reference.

Sample Response:

{  
    "href": "https://api.equinix.com/fabric/v4/connections/3a58dd05-f46d-4b1d-a154-2e85c396ea62",
    "type": "EVPL_VC",
    "uuid": "3a58dd05-f46d-4b1d-a154-2e85c396ea62",
    "name": "Conn-1",
    "state": "PROVISIONING",
    "order": {
        "purchaseOrderNumber": "1-129105284100",
        "billingTier": "Up to 1 Gbps"
    },
    "bandwidth": 1000,
    "redundancy": {
        "group": "b767f685-41b0-1b07-6de0-320a5c00abdd",
        "priority": "SECONDARY"
    },
    "aSide": {
        "accessPoint": {
            "type": "COLO",
            "port": {
                "href": "https://api.equinix.com/fabric/v4/ports/a867f685-41b0-1b07-6de0-320a5c00abdd",
                "type": "XF_PORT",
                "uuid": "a867f685-41b0-1b07-6de0-320a5c00abdd"
            },
            "linkProtocol": {
                "type": "DOT1Q",
                "vlanTag": 1001
            }
        }
    },
    "zSide": {
        "accessPoint": {
            "type": "SP",
            "profile": {
                "href": "https://api.equinix.com/fabric/v4/services/serviceProfiles/20d32a80-0d61-4333-bc03-707b591ae2f5",
                "type": "L2_PROFILE",
                "uuid": "20d32a80-0d61-4333-bc03-707b591ae2f5"
            },
            "location": {
                "href": "https://api.equinix.com/v4/metros/SV", 
                "metroCode": "SV",
                "region": "AMER"
            },
            "linkProtocol": {
                "type": "QINQ",
                "vlanCTag": 1001
            },
            "authenticationKey": "xx-xx-xx",
            "peeringType": "PRIVATE"
        }
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "test@equinix.com",
                "test2@equinix.com"
            ]
        }
    ],
    "operation": {
        "equinixStatus": "PROVISIONING",
        "providerStatus": "PROVISIONING"
    },
    "changeLog": {
        "createdDateTime": "2021-07-15T19:30:29.526Z"
    }
}

Response payload includes configuration parameters defined in the request body. For a full list of possible parameters and their descriptions, see the API Reference.

Connecting to Microsoft Azure ExpressRoute from a QINQ port

To create a connection from your QINQ port to Microsoft Azure ExpressRoute, send a POST request to the /fabric/v4/connections endpoint. Specify your connection's configuration details in the body of the request.

POST /fabric/v4/connections
MethodPOST
Endpoint/fabric/v4/connections
HeadersAuthorization, Content-Type
Path ParametersNot applicable
Query ParametersNot applicable
Body Parameterstype, name, order, bandwidth, redundancy, aSide, zSide, notifications

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": "Conn-1",
    "order": {
        "purchaseOrderNumber": "1-129105284100"
    },
    "bandwidth": 1000,
    "aSide": {
        "accessPoint": {
            "type": "COLO",
            "port": {
                "uuid": "a867f685-41b0-1b07-6de0-320a5c00abdd"
            },
            "linkProtocol": {
                "type": "QINQ",
                "vlanCTag": 1002,
                "vlanSTag": 1003
            }
        }
    },
    "zSide": {
        "accessPoint": {
            "type": "SP",
            "profile": {
                "uuid": "20d32a80-0d61-4333-bc03-707b591ae2f5"
            },
            "location": {
                "metroCode": "SV"
            },
            "linkProtocol": {
                "type": "QINQ",
                "vlanCTag": 1001
            },
            "authenticationKey": "xx-xx-xx"
        }
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "test@equinix.com"
            ]
        }
    ]
}'

The parameters included in the request body are specific to this example. For a full list of parameters and their descriptions, see the API Reference.

Connecting to Microsoft Azure ExpressRoute from a Network Edge Device

To create a connection from your Network Edge device to Microsoft Azure ExpressRoute, send a POST request to the /fabric/v4/connections endpoint. Specify your connection's configuration details in the body of the request.

POST /fabric/v4/connections
MethodPOST
Endpoint/fabric/v4/connections
HeadersAuthorization, Content-Type
Path ParametersNot applicable
Query ParametersNot applicable
Body Parameterstype, name, order, bandwidth, redundancy, aSide, zSide, notifications

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": "Conn-1",
    "order": {
        "purchaseOrderNumber": "1-129105284100"
    },
    "bandwidth": 1000,
    "aSide": {
        "accessPoint": {
        "type": "VD",
        "virtualDevice": {
        "type": "EDGE",
        "uuid": "XXXXXXXXXXXXXXXXXXXXXXXXX"
        },
        "interface": {
            "type": "NETWORK",
            "id": 7
            }
        }
    },
    "zSide": {
        "accessPoint": {
            "type": "SP",
            "profile": {
                "type": "L2_PROFILE",
                "uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
            },
            "location": {
                "metroCode": "SV"
            },
            "authenticationKey": "xx-xx-xx",
            "peeringType": "MICROSOFT"
        }
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "test@equinix.com"
            ]
        }
    ]
}'

The parameters included in the request body are specific to this example. For a full list of parameters and their descriptions, see the API Reference.

Sample Response:

{  
    "type": "EVPL_VC",
    "href": "https://api.equinix.com/fabric/v4/connections/3da14bba-d81c-4497-93c3-3f4a3cb0bc40",
    "uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "name": "vd2azure-vvv-0425a",
    "operation": {
        "providerStatus": "PROVISIONING",
        "equinixStatus": "PROVISIONING"
    },
    "order": {
        "purchaseOrderNumber": "1-1234567890",
        "billingTier": "Up to 200 MB"
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "x@gmail.com"
            ]
        }
    ],
    "changeLog": {
        "createdBy": "fabricamcrh1",
        "createdByFullName": "XXXXXX XXXXXX",
        "createdByEmail": "x@gmail.com",
        "createdDateTime": "2024-04-25T20:30:24.632Z",
        "updatedBy": "fabricamcrh1",
        "updatedByFullName": "fabric amcrh1",
        "updatedByEmail": "x@gmail.com",
        "updatedDateTime": "2024-04-25T20:30:24.632Z"
    },
    "bandwidth": 100,
    "redundancy": {
        "group": "6b869af5-3f89-4329-bb41-ec6f6b053cc4",
        "priority": "PRIMARY"
    },
    "aSide": {
        "accessPoint": {
            "interface": {
                "uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "id": 9,
                "type": "CLOUD"
            },
            "location": {
                "metroCode": "DC"
            },
            "virtualDevice": {
                "uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "type": "EDGE"
            }
        }
    },
    "zSide": {
        "accessPoint": {
            "location": {
                "metroCode": "SV"
            },
            "profile": {
                "href": "https://api.equinix.com/fabric/v4/serviceProfiles/a1390b22-bbe0-4e93-ad37-85beef9d254d",
                "type": "L2_PROFILE",
                "name": "Azure ExpressRoute",
                "uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
            },
            "authenticationKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
    }
}

Response payload includes configuration parameters defined in the request body. For a full list of possible parameters and their descriptions, see the API Reference.

Monitoring the Connection Status

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

Equinix Connection StatesAzure States
equinixStatus attribute valuesproviderStatus attribute valuesProvider StatusPeerings StatusDescription
PROVISIONINGPROVISIONINGNot provisionedNot provisionedConnection request has not been sent to Microsoft yet.
PENDING_BGP_PEERINGPENDING_BGPProvisionedNot provisionedThe connection has been approved and awaits for the customer to configure Microsoft peering on the Microsoft Azure portal. Note that the status will remain PENDING_BGP_PEERING until peering is completed in the Microsoft Azure portal and the status will only change to PROVISIONED once Equinix Fabric syncs with Microsoft. If you want to synchronize the BGP peering instantly, you may use the Equinix Customer Portal.
PROVISIONINGPROVISIONEDProvisioning completed at Microsoft's end and the connection is provisioning at Equinix's end.
PROVISIONEDPROVISIONEDConnection established.

Set Up Microsoft Peering

Log in to the Microsoft Azure portal and configure BGP peering. Refer to the Microsoft documentation for instructions on how to configure peering for an ExpressRoute connection.

Alternatively, you can synchronize peering settings using the Equinix Customer portal or the Connection Actions API endpoin.

Once peering configuration is synchronized, the connection status retrieved via the GET Connections {uuid} should change from Pending-BGP-Peering to Provisioned.