Connect Network Edge Device Using Service Token

Establish a connection between your Network Edge Device and a 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

Retrieve your Network Edge devices information using the Get Virtual Devices API request. There will be just one connection even if your device is a redundant or a cluster device. In case of a redundant device, choose the unique Id of the primary or the secondary device. Similarly, for a cluster device, choose the unique Id of the node0 or the node1.
Use the Get All Service Tokens 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, redundancy, bandwidth, aSide, zSide, notifications

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

Sample curl request - connection from a Network Edge device 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": "VD",
            "virtualDevice": {
                "type": "EDGE",
                "uuid": "fd5342f3-d067-4683-a24f-be952279630b"
            },
            "interface": {
                "type": "NETWORK",
                "id": 5
            }
        }
    },
    "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.
redundancy	Conditional	object	-	-	Redundancy details. This object is not mandatory for primary connections. However, you must provide the redundancy details for secondary connections.
redundancy.priority	Conditional	string	SECONDARY	PRIMARY, SECONDARY	Whether the connection is PRIMARY or SECONDARY. Don't provide a redundancy group for a PRIMARY connection.
redundancy.group	Conditional	string	7a58dd05-f46d-4b1d-a154-2e85c396ea63		Unique Id of the redundancy group. This is only required for secondary connections. If you are creating a secondary connection, enter the group of the PRIMARY. You can find the group of the primary connection by calling Get Specified Connection or by checking the "group" field in the response you receive when creating primary connection.
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	-	-	Object with aSide details.
aSide.accessPoint	Yes	object	-	-	Object with virtual device details.
accessPoint.type	Yes	string	VD	VD	Connection endpoint type. VD - Virtual Device.
accessPoint.virtualDevice	Yes	object			Virtual device details.
virtualDevice.type	Yes	string	EDGE	EDGE	Network Edge device.
virtualDevice.uuid	Yes	string	fd5342f3-d067-4683-a24f-be952279630b	fd5342f3-d067-4683-a24f-be952279630b	The unique Id of a Network Edge device.
accessPoint.interface	Yes	object			Interface details of the virtual device.
interface.type	Yes	string	NETWORK	NETWORK	Type of interface.
interface.id	Yes	string	5	5	Any available interface of the Network Edge device.
zSide	Yes	object	-	-	An object that has zSide connection details.
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	-	Unique ID of a service token.
notifications	yes	array[object]	-	-	Notification preferences.
notifications.type	yes	string	ALL	ALL	Notification preferences for specified assets 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 virtual device to a third-party defined by a service token

{
    "type": "EVPL_VC",
    "href": "http://qa3api.corp.equinix.com/fabric/v4/connections/ebc37e2e-c36b-4e93-86a4-fc4efce7abc8",
    "uuid": "ebc37e2e-c36b-4e93-86a4-fc4efce7abc8",
    "name": "Test ST",
    "state": "ACTIVE",
    "operation": {
        "providerStatus": "AVAILABLE",
        "equinixStatus": "PROVISIONED"
    },
    "notifications": [
        {
            "type": "ALL",
            "emails": [
                "testNEuser2@equinix.com"
            ]
        }
    ],
    "account": {
        "accountNumber": 270235,
        "orgId": 92794,
        "globalOrgId": "0016u000003JZ55AAG"
    },
    "changeLog": {
        "createdBy": "testNEuser2",
        "createdDateTime": "2022-10-05T19:37:12.748Z",
        "updatedBy": "testNEuser2",
        "updatedDateTime": "2022-10-05T19:37:12.748Z"
    },
    "bandwidth": 50,
    "redundancy": {
        "group": "b64dad2a-2763-4084-bc50-b36ef4f67137",
        "priority": "PRIMARY"
    },
    "isRemote": true,
    "direction": "INTERNAL",
    "aSide": {
        "accessPoint": {
            "interface": {
                "uuid": "11fd6067-149f-4142-a5b4-54a8dd6f53fe",
                "id": 6,
                "type": "CLOUD"
            },
            "type": "VD",
            "account": {
                "accountNumber": 270217,
                "organizationName": "eqx-nfv"
            },
            "location": {
                "region": "AMER",
                "metroName": "Ashburn",
                "metroCode": "DC"
            },
            "virtualDevice": {
                "href": "https://api.equinix.com/ne/v1/devices/3539f96c-7f67-4696-90f3-7b6d2fdcde5f",
                "uuid": "3539f96c-7f67-4696-90f3-7b6d2fdcde5f",
                "name": "testing1234",
                "type": "EDGE"
            }
        }
    },
    "zSide": {
        "serviceToken": {
            "uuid": "e05f4f23-d098-4d7c-a9ca-c2897b465107",
            "account": {
                "orgId": 92794
            }
        },
        "accessPoint": {
            "type": "COLO",
            "account": {
                "accountNumber": 270235,
                "organizationName": "testNEuser2-270235"
            },
            "location": {
                "region": "AMER",
                "metroName": "Ashburn",
                "metroCode": "DC"
            },
            "port": {
                "href": "http://qa3api.corp.equinix.com/fabric/v4/ports/c791f8cb-59d0-9d00-8ce0-306a5c00a4ee",
                "uuid": "c791f8cb-59d0-9d00-8ce0-306a5c00a4ee",
                "name": "testNEuser2-DC6-NL-Dot1q-STD-SEC-10G-JN-216"
            },
            "linkProtocol": {
                "type": "DOT1Q",
                "vlanTag": 553
            }
        }
    }
}

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	Status of the connection.
order.billingTier	string	Up to 1 Gbps	Billing tier for connection bandwidth.
bandwidth	integer	1000	Bandwidth of the connection in Mbps.
account	object		Object containing account details of the connection owner.
account.accountNumber	integer	270235	Account number of the connection owner.
account.orgId	integer	92287	Org Id of the account.
account.globalOrgId	string	0016u0000033Z53AAG	Global org Id of the account.
redundancy	object		Object containing redundancy details.
redundancy.group	string	7a58dd05-f46d-4b1d-a154-2e85c396ea63	Unique Id of the redundancy group.
redundancy.priority	string	PRIMARY	Whether the connection is primary or secondary.
isRemote	boolean	true	Whether the connection is remote. The connection is remote if the endpoints are in two different locations.
direction	string	INTERNAL	Direction of the connection (from the requestor's point of view).
aSide	object		Object containing aSide details.
aSide.accessPoint	object		Object containing aSide endpoint configuration.
accessPoint.interface	object		Object containing details of the interface.
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.
accessPoint.type	string	VD	VD: Virtual Device.
accessPoint.account	object		Object containing account details of the aSide account.
account.accountNumber	integer	277689	Account number of the aSide account.
account.organizationName	string	eqx-nfv	Organization name.
location	object		An object that has the location details of the aSide connection.
location.region	string	AMER	Region.
location.metroName	string	Ashburn	Metro name.
location.metroCode	string	DC	Metro code.
virtualDevice	object		An object that has the virtual device details.
virtualDevice.href	string	https://api.equinix.com/ne/v1/devices/5a58dd05-f46d-4b1d-a154-2e85c396ea63	Virtual device.
virtualDevice.uuid	string	5a58dd05-f46d-4b1d-a154-2e85c396ea63	Unique Id of the virtual device.
virtualDevice.name	string	sroy-device	Name of the virtual device.
virtualDevice.type	string	EDGE	Type of virtual device.
zSide	object		Object containing zSide details.
zSide.serviceToken	object		Object containing serviceToken details.
serviceToken.uuid	string	5a58dd05-f46d-4b1d-a154-2e85c396ea63	Unique Id of the service token.
serviceToken.account	object		An object that has the orgId.
account.orgId	integer	92794	Organization Id.
zSide.accessPoint	object		Object containing zSide connection endpoint configuration.
accessPoint.type	string	COLO	Connection endpoint type. COLO - Colocation - space in an IBX data center.
accessPoint.account	object		Object containing account details of the zSide account.
account.accountNumber	integer	277688	Account number of the zSide account.
account.organizationName	string	aws	Organization name.
location	object		An object that has the location details of the zSide connection.
location.region	string	AMER	Region.
location.metroName	string	Ashburn	Metro name.
location.metroCode	string	DC	Metro code.
port	object		An object that has the port details.
port.href	string	https://api.equinix.com/ne/v1/devices/5a58dd05-f46d-4b1d-a154-2e85c396ea63
port.uuid	string	5a58dd05-f46d-4b1d-a154-2e85c396ea63	Unique Id of the port.
port.name	string	sroy-device	Name of the port.
linkProtocol	object		An object that has the link protocol.
linkProtocol.type	string	DOT1Q	Type of link protocol.
linkProtocol.vlanTag	integer	553	Vlan tag.
notifications	array		An array that has notification details.
notifications.type	string	ALL	Type of notification.
notifications.emails	array	test@equinix.com, test2@equinix.com	The list of emails to be notified.
operation	object	-	Preferences and specifications for connection operations.
operation.equinixStatus	string	PROVISIONING	The connection is provisioning.
operation.providerStatus	string	NOT_AVAILABLE	Provider's status towards provisioning a specified connection.
changeLog	object	-	A permanent record of asset creation, modification, or deletion.
changeLog.createdBy	string	testNEuser2	Created by.
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
changeLog.updatedBy	string	testNEuser2	Updated by.
changeLog.updatedDateTime	string	2021-07-15T19:30:29.526Z	Update 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