# Creating Z-Side Service Tokens

A Z-side service token is a unique key that allows another customer on Equinix Fabric to establish a connection to you.

You can create Z-side tokens for the following asset types:

* Fabric Ports (both EVPL, EPL types)
* Network Edge Virtual Devices
* Multipoint Networks - E-LAN, E-Tree, and E-Access.

Once a Z-side service token is created and shared with another customer, they can redeem the token to create a connection with your asset pre-defined as the destination.

![](https://docs.equinix.com/assets/images/token-types-z-side-bd9f62ecc05045fee261e92f3849cfb1.png)

The customer redeeming the Z-side token (the owner of the originating A-side asset) is billed for the virtual connection once they create it. A Z-side service token can also be used to allow another user within your own organization who has assets in a different project so that they may connect to an asset in your project.

For more information on redeeming a Z-side service token, see [Redeeming a Z-side Service Token](https://docs.equinix.com/fabric/service-tokens/redeem-z-side-service-token.md).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before creating a service token, you must have the following:

* A Customer Portal account.
* An existing port, virtual device, or multipoint network.
* Access permissions to an asset that you want to create a service token for.

- Portal
- API

1. Sign in to the [Customer Portal](https://portal.equinix.com/fabric) and navigate to the *Fabric Dashboard*.

2. From the *Service Tokens* menu, select **Create Service Token**.

   ![Screenshot of the Service Token Menu](https://docs.equinix.com/assets/images/create-service-token-drop-down-a304f07e49d3e840e2fa4bbc3c39fb11.png)

3. In the *Service Token Type* section, select **Z-side Service Token**.

   ![Screenshot of Z-side Token Selection](https://docs.equinix.com/assets/images/create-z-side-service-token-type-f956969f0b89eb2733f5845112aab513.png)

Select the asset type for which you want to create the Z-side token: [Port](#create-a-service-token-for-a-port), [Virtual Device](#create-a-service-token-for-a-virtual-device), or [Multipoint Network](#create-a-service-token-for-a-multipoint-network).

1. Authenticate - Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication. Refer to [API Authentication](https://docs.equinix.com/equinix-api/api-authentication.md) for instructions on how to call OAuth API to validate and authenticate your credentials.

2. Determine your Z-side asset information.

   * If you are using a port, send a `GET` request to the [`/fabric/v4/ports`](https://docs.equinix.com/api-catalog/fabricv4/ports/getports.md) endpoint. You need the port UUID(s), port type, link protocol type (DOT1Q or QINQ).

   * If you are using a virtual device, send a `GET` request to the [`/ne/v1/devices`](https://docs.equinix.com/api-catalog/network-edgev1/virtual-device/getvirtualdevices.md) endpoint. You need the device UUID(s). Send a `GET` request to the [`/ne/v1/devices/{device_id}`](https://docs.equinix.com/api-catalog/network-edgev1/virtual-device/getvirtualdevicebyuuid.md) endpoint to get the specifics of a device. You may choose any available interface on the device for your connection. If you do not specify one, the connection is automatically assigned to the next available interface.

   * If you are using a multipoint network, send a `GET` request to the [`/fabric/v4/networks/{networkId}`](https://docs.equinix.com/api-catalog/fabricv4/networks/getnetworkbyuuid.md) endpoint. You need the network's type and UUID.

## Create a Service Token for a Port[​](#create-a-service-token-for-a-port "Direct link to Create a Service Token for a Port")

* Portal
* API

1. In the *Z-side Asset* dropdown, select **Port**.

2. Click **+ Select Port** and choose the specific port for service token from the list. Click **Select Port**.

   ![Screenshot of Select a Port](https://docs.equinix.com/assets/images/create-z-side-select-port-3699435678f4cecf55c1904f5f5fd46b.png)

3. Click **Next**.

4. In *Connection Settings*:

   * Enter the VLAN ID(s) for the connection on your Z-side asset.
   * Select the bandwidths to make available to the token user. Click *Add another bandwidth* to create a custom bandwidth option.
   * Choose whether to allow remote connections. Check the *Allow Remote Connections* box to let token users connect from a different metro than the Z-side asset’s location.

   ![Screenshot of the port connection settings](https://docs.equinix.com/assets/images/create-z-side-port-connection-settings-ba61ce28375f51b5d168e8097cd4dc9c.png)

5. In *Service Token Settings*:

   * Enter an expiration date for the service token. The token must be redeemed by this date or it expires. The maximum date range is 90 days.
   * Enter the email addresses of the users who are authorized to use the service token. You can enter up to 12 recipients. The token can only be used one time by any of the recipients.

   ![Screenshot of the service token settings](https://docs.equinix.com/assets/images/create-z-side-token-settings-6753df20471764af90874cb84d90caed.png)

6. Click **Next**.

7. On the *Review* page, review the information in the *Service Token Type* and *Service Token Settings* panels.

   ![Screenshot of the Review page](https://docs.equinix.com/assets/images/create-z-side-port-review-37854b1a4d89d6b0bae7c93b06ab8a65.png)

   When you are ready, click **Create Service Token**.

To create a Z-side service token for a port, send a `POST` request to the [`/fabric/v4/serviceTokens`](https://docs.equinix.com/api-catalog/fabricv4/service-tokens/createservicetoken.md) endpoint. Provide your connection settings, port details, and service token settings in the body of the request.

* In the `connection` object, specify:

  * The connection type based on the underlying port: `EVPL_VC` or `EPL_VC`.
  * Whether this token can be used to create remote connections.
  * The allowed bandwidth for the connection.
  * Whether this token allows custom bandwidth to be used for the connection.

* In the `zSide` object, specify:

  * The `type` as `COLO`.
  * The port's UUID.
  * the port's link protocol type and appropriate VLAN information.

* Use the `expirationDateTime` field to specify the date and time that the token expires in ISO 8601 format.

* In the `notifications` object, specify the email addresses of the token recipients.

Sample cURL request:

```
curl -X POST 'https://api.equinix.com/fabric/v4/serviceTokens'

-H 'Content-Type: application/json'

-H 'Authorization: Bearer <token>'

-d '{

  "type": "VC_TOKEN",

  "name": "<service_token_name>",

  "description": "<service_token_description>",

  "connection": {

    "type": "EVPL_VC",

    "allowRemoteConnection": <boolean>,

    "allowCustomBandwidth": <boolean>,

    "supportedBandwidths": [

      <bandwidth_speed>,

      <bandwidth_speed>,

      <bandwidth_speed>

    ],

    "zSide": {

      "accessPointSelectors": [

        {

          "type": "COLO",

          "port": {

            "uuid": "<port_uuid>"

          },

          "linkProtocol": {

            "type": "DOT1Q",

            "vlanTag": "<vlan_ID>"

          }

        }

      ]

    }

  },

  "expirationDateTime": "<expiration_date>",

  "notifications": [

    {

      "type": "NOTIFICATION",

      "emails": [

        "<email_address>"

      ]

    }

  ]

}'
```

## Create a Service Token for a Virtual Device[​](#create-a-service-token-for-a-virtual-device "Direct link to Create a Service Token for a Virtual Device")

* Portal
* API

1. In the *Z-side Asset* dropdown, select **Virtual Device**.

2. Choose a virtual device type:

   * Single Device - Single instance virtual devices.
   * Redundant Devices - A pair of redundant virtual devices. **Important**: To create redundant connections to redundant devices, you must create a separate service token for each device in the redundancy pair.
   * Clusters - Clustered virtual devices.

3. Click **+ Select Virtual Device** and select a virtual device instance from the list. Click **Select Virtual Device**.

   ![Screenshot of Select a Virtual Device](https://docs.equinix.com/assets/images/token-select-virtual-device-0f87f45b695b0f229aa1e64af4e28c5d.png)

4. Click **Next**.

5. In *Connection Settings*:

   * Configure the interface to use for the connection. Choose whether to use the next available interface or choose a specific interface.
   * Select the bandwidths to make available to the token user. Click *Add another bandwidth* to create a custom bandwidth option.
   * Choose whether to allow remote connections. Check the *Allow Remote Connections* box to let token users connect from a different metro than the Z-side asset’s location.

   ![Screenshot of the virtual device connection options](https://docs.equinix.com/assets/images/create-z-side-vd-connection-settings-e02423e2a206cd885eabe0b6a974605d.png)

6. In *Service Token Settings*:

   * Enter an expiration date for the service token. The token must be redeemed by this date or it expires. The maximum date range is 90 days.
   * Enter the email addresses of the users who are authorized to use the service token. You can enter up to 12 recipients. The token can only be used one time by any of the recipients.

   ![Screenshot of the service token settings](https://docs.equinix.com/assets/images/create-z-side-token-settings-6753df20471764af90874cb84d90caed.png)

7. Click **Next**.

8. On the *Review* page, review the information in the *Service Token Type* and *Service Token Settings* panels.

   ![Screenshot of Review page](https://docs.equinix.com/assets/images/create-z-side-vd-review-bb50d4f314ff2aa4759c983a68c9fe31.png)

   When you are ready, click **Create Service Token**.

To create a Z-side service token for a virtual device, send a `POST` request to the [`/fabric/v4/serviceTokens`](https://docs.equinix.com/api-catalog/fabricv4/service-tokens/createservicetoken.md) endpoint. Provide your connection settings, virtual device details, and service token settings in the body of the request.

* In the `connection` object, specify:

  * Whether this token can be used to create remote connections.
  * The allowed bandwidth for the connection.
  * Whether this token allows custom bandwidth to be used for the connection.

* In the `zSide` object, specify:

  * The `type` as `VD`.
  * Your virtual devices UUID.
  * The interface to use for the service token's connection. If the `interface` object is omitted, the next available interface on the device is used for the connection.

* Use the `expirationDateTime` field to specify the date and time that the token expires in ISO 8601 format.

* In the `notifications` object, specify the email addresses of the token recipients.

Sample cURL request:

```
curl -X POST 'https://api.equinix.com/fabric/v4/serviceTokens'

-H 'Content-Type: application/json'

-H 'Authorization: Bearer <token>'

-d '{

  "type": "VC_TOKEN",

  "name": "<service_token_name>",

  "description": "<service_token_description>",

  "connection": {

    "type": "EVPL_VC",

    "allowRemoteConnection": <boolean>,

    "allowCustomBandwidth": <boolean>,

    "supportedBandwidths": [

      <bandwidth_speed>,

      <bandwidth_speed>,

      <bandwidth_speed>

    ],

    "zSide": {

      "accessPointSelectors": [

        {

          "type": "VD",

          "virtualDevice": {

            "type": "EDGE",

            "uuid": "<virtual_device_uuid>"

          },

          "interface": {

            "type": "NETWORK",

            "id": <interface_id>

          }

        }

      ]

    }

  },

  "expirationDateTime": "<expiration_date>",

  "notifications": [

    {

      "type": "NOTIFICATION",

      "emails": [

        "<email_address>"

      ]

    }

  ]

}'
```

## Create a Service Token for a Multipoint Network[​](#create-a-service-token-for-a-multipoint-network "Direct link to Create a Service Token for a Multipoint Network")

* Portal
* API

1. In the *Z-side Asset* dropdown, select **Multipoint Network**.

2. Click **+ Select Network** and select the multipoint network from the list. Click **Select Network**.

   ![](https://docs.equinix.com/assets/images/token-select-multipoint-network-51da1f46348538b8483ea5650ac30902.png)

3. Click **Next**.

4. In *Connection Settings*:

   * Note that connections created from E-Tree service tokens will default to Leaf. As the owner of the network, you can edit the connection role to Root once the service token is redeemed and the connection has been provisioned.
   * Select the bandwidths to make available to the token user. Click *Add another bandwidth* to create a custom bandwidth option.

   ![Screenshot of the network connection options](https://docs.equinix.com/assets/images/create-z-side-network-connection-settings-9672f67dd165d7fad1253e32a91354da.png)

5. In *Service Token Settings*:

   * Enter an expiration date for the service token. The token must be redeemed by this date or it expires. The maximum date range is 90 days.
   * Enter the email addresses of the users who are authorized to use the service token. You can enter up to 12 recipients. The token can only be used one time by any of the recipients.

   ![Screenshot of the service token settings](https://docs.equinix.com/assets/images/create-z-side-token-settings-6753df20471764af90874cb84d90caed.png)

6. Click **Next**.

7. On the *Review* page, review the information in the *Service Token Type* and *Service Token Settings* panels.

   ![Screenshot of Review page](https://docs.equinix.com/assets/images/create-z-side-network-review-7feadb088aede6c25a8439957ae18613.png)

   When you are ready, click **Create Service Token**.

To create a Z-side service token for a multipoint network, send a `POST` request to the [`/fabric/v4/serviceTokens`](https://docs.equinix.com/api-catalog/fabricv4/service-tokens/createservicetoken.md) endpoint. Provide your connection settings, network details, and service token settings in the body of the request.

* In the `connection` object, specify:

  * The connection type as `EVPLAN_VC`, `EPLAN_VC`, `EVPTREE_VC` or `EPTREE_VC` depending on your network configuration.
  * Whether this token can be used to create remote connections.
  * The allowed bandwidth for the connection.
  * Whether this token allows custom bandwidth to be used for the connection.

* In the `zSide` object:

  * Specify the `type` as `NETWORK`.
  * Indicate the network type as `EVPLAN`, `EPLAN`, `EVPTREE`, or `EPTREE`.
  * Provide your network's UUID.

* Use the `expirationDateTime` field to specify the date and time that the token expires in ISO 8601 format.

* In the `notifications` object, specify the email addresses of the token recipients.

Sample cURL request:

```
curl -X POST 'https://api.equinix.com/fabric/v4/serviceTokens'

-H 'Content-Type: application/json'

-H 'Authorization: Bearer <token>'

-d '{

  "type": "VC_TOKEN",

  "name": "<service_token_name>",

  "description": "<service_token_description>",

  "connection": {

    "type": "EVPLAN_VC",

    "allowRemoteConnection": <boolean>,

    "supportedBandwidths": [

      <bandwidth_speed>,

      <bandwidth_speed>,

      <bandwidth_speed>

    ],

    "zSide": {

      "accessPointSelectors": [

        {

          "type": "NETWORK",

          "network": {

            "type": "EVPLAN",

            "uuid": "<network_uuid>"

          }

        }

      ]

    }

  },

  "expirationDateTime": "<token_expiration_date>",

  "notifications": [

    {

      "type": "NOTIFICATION",

      "emails": [

        "<email_address>"

      ]

    }

  ]

}'
```

## Service Token Status[​](#service-token-status "Direct link to Service Token Status")

Once you have created a service token, you can check its status, including whether it has been redeemed by the other customer. If the status is `Inactive`, the service token hasn't been redeemed yet. If the status is `Active`, the service token has been redeemed.

> **Note**
>
> The creator of the connection using a Z-side token is billed for the connection.

If the status is `Expired`, the service token has reached its expiration date without being redeemed.

* Portal
* API

To check your service token status, sign into the [Customer Portal](https://portal.equinix.com/fabric) and navigate to your [Service Token Inventory](https://docs.equinix.com/fabric/service-tokens/service-token-inventory.md)

![](https://docs.equinix.com/assets/images/create-a-side-inventory-ffd1e8fb00db4b9dfc7b80726bb1bb35.png)

To check the status of your service tokens, send a `GET` request to the [`/fabric/v4/serviceTokens`](https://docs.equinix.com/api-catalog/fabricv4/service-tokens/getservicetokens.md) endpoint. The response includes a list of your service tokens along with their statuses in the `state` field.

Sample cURL Request:

```
curl -X GET 'https://api.equinix.com/fabric/v4/serviceTokens'

-H 'Authorization: Bearer <token>'
```

More information on managing service tokens is available on the [Service Token Inventory](https://docs.equinix.com/fabric/service-tokens/service-token-inventory.md) page.