Connect Using Service Token

Establish a connection between your IBX colocated assets and a third-party, based on the parameters defined in the service token. The Z-side can be Colo, Network Edge, or Network service token.

Step 1: Authenticate

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

Refer to Generating Client ID and Client Secret under the Getting Access Token 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 Fabric, contact your local Equinix Service Desk.

Step 2: Get Attribute Information

1. Determine A-side port information
Get your Equinix Fabric ports information by calling Get All Ports .

2. List available service tokens and get connection details
Call Get All Service Tokens to find available service tokens along with the allowed connection settings.

Step 3: Create Connection

Use POST /fabric/v4/connections API request to create a connection.

A service token can be dispatched to a number of recipients, and it's valid for a single use by any of them.

POST /fabric/v4/connections
Method POST
Endpoint /fabric/v4/connections
Headers Authorization, Content-Type
Path Parameters Not applicable
Query Parameters Not applicable
Body Parameters type, name, order, bandwidth, aSide, zSide, notifications

Call Retrieve Pricing to get connection price estimate.


Sample curl request - connection from a DOT1Q port to a service token

Copy 
curl -X
POST 'https://api.equinix.com/fabric/v4/connections'
-H 'content-type: application/json'
-H 'authorization: Bearer qwErtY8zyW1abcdefGHI'
-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": {
        "serviceToken": {
            "uuid": "20d32a80-0d61-4333-bc03-707b591ae2f4"
        }
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "test@equinix.com",
                "test2@equinix.com"
            ]
        }
    ]
}'

Sample curl request - connection from a QINQ port to a service token

Copy 
curl -X
POST 'https://api.equinix.com/fabric/v4/connections'
-H 'content-type: application/json'
-H 'authorization: Bearer qwErtY8zyW1abcdefGHI'
-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": 1001,
                "vlanSTag": 1002
            }
        }
    },
    "zSide": {
        "serviceToken": {
            "uuid": "20d32a80-0d61-4333-bc03-707b591ae2f4"
        }
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "test@equinix.com",
                "test2@equinix.com"
            ]
        }
    ]
}'

Body parameters

Parameter Mandatory Type Example values Applicable values Description
type Yes string EVPL_VC

  • EVPL_VC

  • EVPLAN_VC

  • EPLAN_VC

Connection type.

EVPL_VC - Ethernet virtual private line connection type used for tagged layer 2 connections.

EVPLAN_VC

EPLAN_VC
name Yes string Conn-1 Maximum: 24 characters
Allowed characters: alpha-numeric, hyphens ('-') and underscores ('_') 		Connection name.
order No object - - Order details.
order.purchaseOrderNumber No string 1-129105284100 - Subscriber's purchase order identifier.
bandwidth Yes integer 1000

Use the Get Specified Service Token API to retrieve details on available connection speeds.

Connection bandwidth in Mbps.
aSide Yes object - - Source port definition.
aSide.accessPoint Yes object - - Connection endpoint configuration.
accessPoint.type Yes string COLO COLO Connection endpoint type.

COLO - Colocation space in an IBX data center.
accessPoint.port Yes object - - Port associated with the connection.
port.uuid Yes string a867f685-41b0-1b07-6de0-320a5c00abdd - Equinix-assigned port identifier.
accessPoint.linkProtocol Yes object - - Link protocol configuration.
linkProtocol.type Yes string DOT1Q DOT1Q
QINQ		 Link protocol type.
linkProtocol.vlanTag Yes integer 1001 Range: 2-4094 DOT1Q protocol VLAN tag.
linkProtocol.vlanCTag Yes integer 1002 Range: 2-4094 QINQ protocol, inner VLAN customer frame tag used to identify packets as they traverse trunk lines.
linkProtocol.vlanSTag Yes integer 1003 Range: 2-4094 QINQ protocol, outer VLAN service frame tag used to identify packets as they traverse trunk lines.
zSide Yes object - - Destination port definition.
zSide.serviceToken Yes object - - Authorization token created by the provider (Z-side) to allow the subscriber (A-side) to establish a connection. You can have Colo, Network Edge, or Network service token.
serviceToken.uuid Yes object 20d32a80-0d61-4333-bc03-707b591ae2f4 - Service token identifier.
notifications yes array[object] - - Subscriber preferences for notification of changes in asset configuration or status.
notifications.type yes string ALL ALL Notification preferences for a specified asset, such as a service token, port, access point, or profile.
notifications.emails yes array[string] ["john@equinix.com", "jenkins@equinix.com"] Minimum: 1
Maximum: 12		 List of up to 12 recipients.

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


Sample response - connection from a DOT1Q port to a Z-side Port service token

Copy 
{
    "href": "https://api.equinix.com/fabric/v4/connections/3a58dd05-f46d-4b1d-a154-2e85c396ea62",
    "type": "EVPL_VC",
    "uuid": "3a58dd05-f46d-4b1d-a154-2e85c396ea62",
    "state": "PROVISIONING",
    "name": "Conn-1",
    "order": {
        "purchaseOrderNumber": "1-129105284100",
        "billingTier": "Up to 1 Gbps"
    },
    "bandwidth": 1000,
    "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": {
        "serviceToken": {
            "href": "https://api.equinix.com/fabric/v4/serviceTokens/25acdea5-1eeb-4f0b-8ca9-6c505f46847d",
            "uuid": "25acdea5-1eeb-4f0b-8ca9-6c505f46847d"
        },
        "accessPoint": {
            "location": {
                "metroHref" : "https://api.equinix.com/fabric/v4/metros/DC",
                "region": "AMER",
                "metroName": "Ashburn",
                "metroCode": "DC"
            },
            "port": {
                "type": "XF_PORT",
                "href": "https://api.equinix.com/fabric/v4/ports/c5720fcc-4ae7-ae7e-13e0-306a5c00adaf",
                "uuid": "c5720fcc-4ae7-ae7e-13e0-306a5c00adaf",
                "name": "eqx-nfv-CX-DC6-L-Dot1q-BO-10G-PRI-JUN-7"
            },
            "linkProtocol": {
                "type": "DOT1Q",
                "vlanTag": 3132
            }
        }
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "test@equinix.com",
                "test2@equinix.com"
            ]
        }
    ],
    "operation": {
        "equinixStatus": "PROVISIONING",
        "providerStatus": "NOT_AVAILABLE"
    },
    "changeLog": {
        "createdDateTime": "2021-07-15T19:30:29.526Z"
    }
}

Response payload body description

Response payload includes configuration parameters defined in the request body. The following table contains descriptions of additional information included in the response payload. For descriptions of the remaining fields, refer to the Body parameters section.

Parameter Type Example values Description
href string https://api.equinix.com/fabric/v4/connections/3a58dd05-f46d-4b1d-a154-2e85c396ea62 An absolute URL that returns the specified connection.
uuid string 3a58dd05-f46d-4b1d-a154-2e85c396ea62 Equinix-assigned connection identifier.
state string PROVISIONING Lifecycle stage of a connection.
order.billingTier string Up to 1 Gbps Billing tier for connection bandwidth.
port.href string https://api.equinix.com/fabric/v4/ports/a867f685-41b0-1b07-6de0-320a5c00abdd An absolute URL that returns the specified port.
port.type string XF_PORT Type of port.

XF_PORT - Equinix Fabric port used as a Fabric connection endpoint.
zSide object Object containing zSide details.
zSide.accessPoint object Object containing zSide endpoint configuration.
accessPoint.interface object Object containing details of the interface. Only relevant for Network Edge service token.
interface.uuid string 3a58dd05-f46d-4b1d-a154-2e85c396ea62 Unique identifier of the interface.
interface.id string 5 The interface id of the virtual device that hosts the connection.
interface.type string CLOUD

Type of interface.

  • CLOUD
  • NETWORK
accessPoint.location object An object that has the location details of the zSide connection.
location.metroHref string https://api.equinix.com/fabric/v4/metros/SV URL that returns the specified metro.
location.region string AMER Region.
location.metroName string Ashburn Metro name.
location.metroCode string DC Metro code.
accessPoint.virtualDevice object An object that has the virtual device details. Only relevant for Network Edge service token.
virtualDevice.href string https://api.equinix.com/ne/v1/devices/5a58dd05-f46d-4b1d-a154-2e85c396ea63 URL that has the specified Network Edge asset.
virtualDevice.uuid string 5a58dd05-f46d-4b1d-a154-2e85c396ea63 Unique Id of the virtual device.
virtualDevice.type string EDGE Type of virtual device.
zSide.serviceToken object An object that has the service token details.
serviceToken.href string https://api.equinix.com/fabric/v4/serviceTokens/20d32a80-0d61-4333-bc03-707b591ae2f5 An absolute URL that returns the specified service token.
serviceToken.uuid string 25acdea5-1eeb-4f0b-8ca9-6c505f46847d

Unique Id of the service token.
accessPoint.network object Object containing network configuration. Only relevant for Network service token.
network.href string http://api.equinix.com/fabric/v4/networks/7c4f2315-839b-4fbd-90ea-59adf165312d An absolute URL that returns the network asset.
network.uuid string 3a58dd05-f46d-4b1d-a154-2e85c396ea62 Equinix-assigned network identifier.
network.name string EVPLAN_NETWORK Name of the network.
network.state string ACTIVE Status of the network.
network.type string EVPLAN

Type of network.

  • EVPLAN

  • EPLAN
network.scope string REGIONAL

Scope of network.

  • LOCAL,

  • REGIONAL

  • GLOBAL
operation object - Preferences and specifications of connection operations.
operation.equinixStatus string PROVISIONING Progress towards provisioning a specified connection.
operation.providerStatus string NOT_AVAILABLE Provider's progress towards provisioning a specified connection.
changeLog object - A permanent record of asset creation, modification, or deletion.
changeLog.createdDateTime string 2021-07-15T19:30:29.526Z Connection creation timestamp in the IETF ISO 8601 extended date/time format:

YYYY-MM-DDTHH:MM:SS.000+0000

Call Get Specified Connection to monitor your connection status.