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.

connectToServiceToken_2_0

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
Retrieve your Equinix Fabric ports information using the Get All Ports API request.

2. List available service tokens and get connection details
Use the Get All Service Tokens API request to retrieve 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

Use the Retrieve Pricing API request to retrieve connection price estimate.

Sample curl request - connection from a DOT1Q port to a third-party defined by a service token

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 third-party defined by a service token

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	Connection type. EVPL_VC - Ethernet virtual private line connection type used for tagged layer 2 connections.
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.
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 third-party defined by a service token

{
    "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/20d32a80-0d61-4333-bc03-707b591ae2f5",
            "type": "VC_TOKEN",
            "uuid": "20d32a80-0d61-4333-bc03-707b591ae2f5"
        }
    },
    "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.
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.type	string	VC_TOKEN	Service token type. VC_TOKEN - Service token defining a Fabric connection.
operation	object	-	Preferences and specifications for 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

Use the Get Specified Connection API request to monitor connection status.

Step 1: Authenticate​

Step 2: Get Attribute Information​

Step 3: Create Connection​

Step 1: Authenticate

Step 2: Get Attribute Information

Step 3: Create Connection