List gateways

GET /gateways

List all Direct Link gateways in this account. Gateways in other accounts with connections to networks in this account are also returned.

Request

Response

200 - Successfully retrieved the list of gateways.

gateways

array

Collection of Direct Link gateways

Create gateway

POST /gateways

Creates a Direct Link gateway based on the supplied template.

Request

Request Body

GatewayTemplate

The Direct Link Gateway template

as_prepends

array

array of AS Prepend configuration information.

authentication_key

AuthenticationKeyIdentity

bfd_config

GatewayBfdConfigTemplate

BFD configuration information.

interval

Required *

integer

Minimum interval in milliseconds at which the local routing device transmits hello packets and then expects to receive a reply from a neighbor with which it has established a BFD session.

multiplier

integer

The number of hello packets not received by a neighbor that causes the originating interface to be declared down.

bgp_asn

Required *

integer

BGP ASN

bgp_base_cidr

string

(DEPRECATED) BGP base CIDR.

Field is deprecated. See bgp_ibm_cidr and bgp_cer_cidr for details on how to create a gateway using either automatic or explicit IP assignment. Any bgp_base_cidr value set will be ignored.

Deprecated field bgp_base_cidr will be removed from the API specification after 15-MAR-2021.

bgp_cer_cidr

string

BGP customer edge router CIDR.

For auto IP assignment, omit bgp_cer_cidr and bgp_ibm_cidr. IBM will automatically select values for bgp_cer_cidr and bgp_ibm_cidr.

For explicit IP assignment set a valid bgp_cer_cidr and bgp_ibm_cidr CIDR, the value must reside in one of "10.254.0.0/16", "172.16.0.0/12", "192.168.0.0/16", "169.254.0.0/16" or an owned public CIDR. bgp_cer_cidr and bgp_ibm_cidr must have matching network and subnet mask values.

bgp_ibm_cidr

string

BGP IBM CIDR.

For auto IP assignment, omit bgp_cer_cidr and bgp_ibm_cidr. IBM will automatically select values for bgp_cer_cidr and bgp_ibm_cidr.

connection_mode

string

Type of services this Gateway is attached to. Mode transit means this Gateway will be attached to Transit Gateway Service and direct means this Gateway will be attached to vpc or classic connection. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

default_export_route_filter

object

The default directional route filter action that applies to routes that do not match any directional route filters.

default_import_route_filter

object

The default directional route filter action that applies to routes that do not match any directional route filters.

export_route_filters

RouteFilterCollectionTemplate

Array of directional route filters for a Direct Link gateway. When creating a gateway or replacing existing route filters, the order of the items in the array will set the ordering of the list of route filters.

global

Required *

boolean

Gateways with global routing (`true`) can connect to networks outside their associated region.

import_route_filters

RouteFilterCollectionTemplate

metered

Required *

boolean

Metered billing option. When `true` gateway usage is billed per gigabyte. When `false` there is no per gigabyte usage charge, instead a flat rate is charged for the gateway.

name

Required *

string

The unique user-defined name for this gateway.

patch_panel_completion_notice

string

Gateway patch panel complete notification from implementation team

resource_group

ResourceGroupIdentity

Resource group for this resource. If unspecified, the account's default resource group is used.

id

Required *

object

Resource group ID.

speed_mbps

Required *

integer

Gateway speed in megabits per second

type

Required *

string

Offering type

Response

201 - The Direct Link gateway was created successfully.

as_prepends

array

array of AS Prepend information.

authentication_key

AuthenticationKeyReference

bfd_config

GatewayBfdConfig

BFD configuration information.

bgp_asn

integer

Customer BGP ASN

bgp_base_cidr

string

(DEPRECATED) BGP base CIDR is deprecated and no longer recognized by the Direct Link APIs.

See bgp_cer_cidr and bgp_ibm_cidr fields instead for IP related information.

Deprecated field bgp_base_cidr will be removed from the API specification after 15-MAR-2021.

bgp_cer_cidr

string

BGP customer edge router CIDR

bgp_ibm_asn

integer

IBM BGP ASN

bgp_ibm_cidr

string

BGP IBM CIDR

bgp_status

string

Gateway BGP status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

bgp_status_updated_at

string

Date and time bgp status was updated

carrier_name

string

Carrier name. Only set for type=dedicated gateways.

change_request

object

Changes pending approval for provider managed Direct Link Connect gateways.

completion_notice_reject_reason

string

Reason for completion notice rejection. Only included on type=dedicated gateways with a rejected completion notice.

connection_mode

string

created_at

string

The date and time resource was created

crn

string

The CRN (Cloud Resource Name) of this gateway

cross_account

boolean

Indicates whether this gateway is cross account gateway.

cross_connect_router

string

Cross connect router. Only included on type=dedicated gateways.

customer_name

string

Customer name. Only set for type=dedicated gateways.

default_export_route_filter

string

The default directional route filter action that applies to routes that do not match any directional route filters.

default_import_route_filter

string

The default directional route filter action that applies to routes that do not match any directional route filters.

global

boolean

Gateways with global routing (`true`) can connect to networks outside their associated region.

id

string

The unique identifier of this gateway

link_status

string

Gateway link status. Only included on type=dedicated gateways. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

link_status_updated_at

string

Date and time link status was updated

location_display_name

string

Gateway location long name

location_name

string

Gateway location

macsec

GatewayMacsecReference

MACsec configuration information of a direct link.

macsec_capability

GatewayMacsecCapability

Indicates the direct link's MACsec capability. It must match one of the MACsec related `capabilities` of the `cross_connect_router`.

Only included on type=dedicated direct links.

`non_macsec`: The direct link does not support MACsec.
`macsec`: The direct link supports MACsec. The MACsec feature must be enabled.
`macsec_optional`: The direct link supports MACsec. The MACsec feature is not required and can be enabled after direct link creation.

metered

boolean

Metered billing option. When `true` gateway usage is billed per gigabyte. When `false` there is no per gigabyte usage charge, instead a flat rate is charged for the gateway.

name

string

The unique user-defined name for this gateway.

operational_status

string

Gateway operational status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

See `operational_status_reasons[]` for possible remediation of the `failed` `operational_status`.

operational_status_reasons

array

Context for certain values of `operational_status`.

patch_panel_completion_notice

string

Gateway patch panel complete notification from implementation team

port

GatewayPortReference

Port information for type=connect gateways.

provider_api_managed

boolean

Indicates whether gateway changes must be made via a provider portal.

resource_group

ResourceGroupReference

Resource group reference

speed_mbps

integer

Gateway speed in megabits per second

type

string

Offering type. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

vlan

integer

VLAN configured for this gateway. If there is no vlan configured for the gateway, the vlan will be absent. This property will also be absent if this gateway's `crn` is in another account.

400 - An invalid Direct Link template was provided.

errors

array

Array of errors

trace

object

unique identfier

List AS Prepends

GET /gateways/{gateway_id}/as_prepends

Retrieve all AS Prepends for the specified Direct Link gateway.

Request

Response

200 - AS Prepends retrieved successfully.

as_prepends

array

array of AS Prepend information.

404 - The specified Direct Link gateway could not be found.

errors

array

Array of errors

trace

object

unique identfier

Replace existing AS Prepends

PUT /gateways/{gateway_id}/as_prepends

Replace the given set of AS prepends on the specified gateway. Existing resources may be reused when the individual AS Prepend item is unchanged.

Request

Request Body

AsPrependReplaceTemplate

The AS Prepend replace template

as_prepends

array

array of AS Prepend configuration information.

Path Parameters

Query Parameters

Response

201 - AS Prepends replaced successfully.

as_prepends

array

array of AS Prepend information.

400 -

404 -

412 - The provided `If-Match` value does not match the current ETag value of the AS Prepends

errors

array

Array of errors

trace

object

unique identfier

List export route filters

GET /gateways/{gateway_id}/export_route_filters

List all export route filters that influence the export routes advertised to the on premises network and learned from attached virtual connections of the Direct Link gateway.

The first export route filter an export route matches will determine whether the route is permitted or denied to be advertised by the Direct Link gateway. Route filter order is determined by the filter's `before` field.

If an export route does not match any of the export route filters, the route is subject to the `default_export_route_filter` of the direct link.

Request

Response

200 - Export route filters retrieved successfully.

export_route_filters

array

Array of export route filters

404 -

Create an export route filter

POST /gateways/{gateway_id}/export_route_filters

Create a new export route filter to be configured on the Direct Link gateway.

This call can result in an implicit update to another route filter's `before` field.

If the request's route filter template does not contain a `before` field, the created filter will be added to the end of of the list. The filter previously at the end of the list will have it's `before` field set to the created route filter.

If the request's route filter template contains a `before` field, the created filter will be added directly before that specified route filter. If the specified route filter has a preceding route filter, that filter's `before` field is updated to the created route filter.

Request

Request Body

CreateRouteFilterTemplate

The export route filter create template

action

Required *

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

Required *

string

IP prefix representing an address and mask length of the prefix-set

Response

201 - Direct Link gateway export route filter was created successfully.

action

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

created_at

string

The date and time the route filter was created in ISO 8601 format

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

id

string

The identifier of a route filter

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

string

IP prefix representing an address and mask length of the prefix-set

updated_at

string

The date and time the route filter was last updated

400 -

404 -

Replace existing export route filters

PUT /gateways/{gateway_id}/export_route_filters

Replace all existing export route filters configured on the Direct Link gateway

Request

Request Body

ExportRouteFiltersReplaceTemplate

export_route_filters

RouteFilterCollectionTemplate

Path Parameters

Query Parameters

Response

201 - Export route filters replaced successfully.

export_route_filters

array

Array of export route filters

400 -

404 -

412 - The provided `If-Match` value does not match the current ETag value of the export route filters

errors

array

Array of errors

trace

object

unique identfier

Remove export route filter from Direct Link gateway

DELETE /gateways/{gateway_id}/export_route_filters/{id}

Delete an export route filter.

Deleting an export route filter will implicitly update the preceding filter's `before` field to the filter that follows the deleted filter. The preceding filter will result with an empty `before` field if there is no filter following the deleted route filter.

Request

Response

204 - The export route filter was deleted successfully.

404 -

Retrieves the specified Direct Link gateway export route filter

GET /gateways/{gateway_id}/export_route_filters/{id}

Retrieve an export route filter from the Direct Link gateway.

Request

Response

200 - The export route filter was retrieved successfully.

action

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

created_at

string

The date and time the route filter was created in ISO 8601 format

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

id

string

The identifier of a route filter

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

string

IP prefix representing an address and mask length of the prefix-set

updated_at

string

The date and time the route filter was last updated

404 -

Updates the specified Direct Link gateway export route filter

PATCH /gateways/{gateway_id}/export_route_filters/{id}

Update an export route filter from the Direct Link gateway.

Updating a route filter's `before` field will result in implicit updates to other route filters' `before` fields.

Considering the updated filter prior to the update, the preceding route filter's `before` field will be set to the filter following the updating route filter, if present. Otherwise it is set to empty.

Considering the updated filter after the update, if the new filter following the updated filter has an existing filter preceding it, that preceding filter's `before` field will be set to the updated filter.

Request

Request Body

The export route filter update template

Response

200 - The export route filter was updated successfully.

action

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

created_at

string

The date and time the route filter was created in ISO 8601 format

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

id

string

The identifier of a route filter

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

string

IP prefix representing an address and mask length of the prefix-set

updated_at

string

The date and time the route filter was last updated

400 -

404 -

List import route filters

GET /gateways/{gateway_id}/import_route_filters

List all import route filters that influence the import routes learned from the on premises network.

The first import route filter an import route matches will determine whether the route is permitted or denied to be learned by the Direct Link gateway. Route filter order is determined by the filter's `before` field.

If an import route does not match any of the import route filters, the route is subject to the `default_import_route_filter` of the direct link.

Request

Response

200 - Import route filters retrieved successfully.

import_route_filters

array

Array of import route filters

404 -

Create an import route filter

POST /gateways/{gateway_id}/import_route_filters

Create a new import route filter to be configured on the Direct Link gateway.

This call can result in an implicit update to another route filter's `before` field.

Request

Request Body

CreateRouteFilterTemplate

The import route filter create template

action

Required *

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

Required *

string

IP prefix representing an address and mask length of the prefix-set

Response

201 - Direct Link gateway import route filter was created successfully.

action

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

created_at

string

The date and time the route filter was created in ISO 8601 format

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

id

string

The identifier of a route filter

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

string

IP prefix representing an address and mask length of the prefix-set

updated_at

string

The date and time the route filter was last updated

400 -

404 -

Replace existing import route filters

PUT /gateways/{gateway_id}/import_route_filters

Replace all existing import route filters configured on the Direct Link gateway

Request

Request Body

ImportRouteFiltersReplaceTemplate

import_route_filters

RouteFilterCollectionTemplate

Path Parameters

Query Parameters

Response

201 - Import route filters replaced successfully.

import_route_filters

array

Array of import route filters

400 -

404 -

412 - The provided `If-Match` value does not match the current ETag value of the export route filters

errors

array

Array of errors

trace

object

unique identfier

Remove import route filter from Direct Link gateway

DELETE /gateways/{gateway_id}/import_route_filters/{id}

Delete an import route filter.

Deleting an import route filter will implicitly update the preceding filter's `before` field to the filter that follows the deleted filter. The preceding filter will result with an empty `before` field if there is no filter following the deleted route filter.

Request

Response

204 - The import route filter was deleted successfully.

404 -

Retrieves the specified Direct Link gateway import route filter

GET /gateways/{gateway_id}/import_route_filters/{id}

Retrieve an import route filter from the Direct Link gateway.

Request

Response

200 - The import route filter was retrieved successfully.

action

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

created_at

string

The date and time the route filter was created in ISO 8601 format

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

id

string

The identifier of a route filter

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

string

IP prefix representing an address and mask length of the prefix-set

updated_at

string

The date and time the route filter was last updated

404 -

Updates the specified Direct Link gateway import route filter

PATCH /gateways/{gateway_id}/import_route_filters/{id}

Update an import route filter from the Direct Link gateway.

Updating a route filter's `before` field will result in implicit updates to other route filters' `before` fields.

Request

Request Body

The import route filter update template

Response

200 - The import route filter was updated successfully.

action

string

Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter

before

string

Identifier of the next route filter considered if a route does not match the current filter. This property builds the ordering among route filters and follows semantics:

When before is an identifier of a route filter that exists and is in the same collection, a route will first attempt to match on the current filter before preceding to the filter referenced in this property.
When a filter is created with before that matches another filter in the same collection, the existing filter will take precedence. The before of the existing filter will be updated to refer to the newly created filter. The newly created filter will refer to the route filter identified by the provided before.
When a filter is created without a before, it takes the lowest precedence. The existing filter of lowest precedence will be updated to refer to the newly created filter.

created_at

string

The date and time the route filter was created in ISO 8601 format

ge

integer

The minimum matching length of the prefix-set (mnemonic for greater than or equal to).

id

string

The identifier of a route filter

le

integer

The maximum matching length of the prefix-set (mnemonic for less than or equal to).

prefix

string

IP prefix representing an address and mask length of the prefix-set

updated_at

string

The date and time the route filter was last updated

400 -

404 -

List route reports

GET /gateways/{gateway_id}/route_reports

Retrieve all route reports for the specified Direct Link gateway.

Request

Response

200 - Reports retrieved successfully.

route_reports

array

Array of route reports

404 - The specified Direct Link gateway could not be found.

errors

array

Array of errors

trace

object

unique identfier

Request a route report

POST /gateways/{gateway_id}/route_reports

Request route report generation. While report generation is in progress, additional requests to generate a report are ignored and return the current pending report. While `status` is `pending`, `gateway_routes`, `on_prem_routes`, `virtual_connection_routes`, and `overlapping_routes` will be empty arrays. These fields will be filled when the `status` enters the `complete` status. Call `get_gateway_route_report` with the pending route report's `id` to check on the current status of the report.

Request

Response

202 - Route report request successful. If not already in progress, report generation has begun.

advertised_routes

array

Array of connection prefixes advertised to the on-prem network. This parameter is not returned when the route report was generated prior to inclusion of this parameter.

created_at

string

Date and time route report was requested

gateway_routes

array

Array of local/direct routes

id

string

Report identifier

on_prem_routes

array

Array of on premises routes

overlapping_routes

array

Array of overlapping routes

status

string

Route report status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

updated_at

string

Date and time route report was last modified

virtual_connection_routes

array

Array of routes on virtual connections

404 - The specified Direct Link gateway could not be found.

errors

array

Array of errors

trace

object

unique identfier

Delete route report

DELETE /gateways/{gateway_id}/route_reports/{id}

Delete a route report.

Request

Response

204 - Route report deleted successfully.

404 - A Direct Link gateway or route report with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Retrieve route report

GET /gateways/{gateway_id}/route_reports/{id}

Retrieve a route report.

Request

Response

200 - Route report retrieved successfully.

advertised_routes

array

Array of connection prefixes advertised to the on-prem network. This parameter is not returned when the route report was generated prior to inclusion of this parameter.

created_at

string

Date and time route report was requested

gateway_routes

array

Array of local/direct routes

id

string

Report identifier

on_prem_routes

array

Array of on premises routes

overlapping_routes

array

Array of overlapping routes

status

string

Route report status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

updated_at

string

Date and time route report was last modified

virtual_connection_routes

array

Array of routes on virtual connections

404 - A route report or gateway with the specified identifier(s) could not be found.

errors

array

Array of errors

trace

object

unique identfier

List virtual connections

GET /gateways/{gateway_id}/virtual_connections

List a gateway's virtual connections.
For gateway in other account with virtual connections that connect to network in this account. Only virtual connections that connect to this account are returned.

Request

Response

200 - The virtual connections were retrieved successfully.

virtual_connections

array

virtual connection array

404 - The specified virtual connection could not be found.

errors

array

Array of errors

trace

object

unique identfier

Create virtual connection

POST /gateways/{gateway_id}/virtual_connections

Create a virtual connection to the specified network.

Request

Request Body

GatewayVirtualConnectionTemplate

The virtual connection template

name

Required *

string

The user-defined name for this virtual connection. Virtual connection names are unique within a gateway. This is the name of the virtual connection itself, the network being connected may have its own name attribute.

network_id

string

Unique identifier of the target network. For type=vpc virtual connections this is the CRN of the target VPC. This field does not apply to type=classic connections.

type

Required *

string

The type of virtual connection

Response

201 - The virtual connection was created successfully.

created_at

string

The date and time resource was created

id

object

unique identifier

name

string

network_account

string

For virtual connections across two different IBM Cloud Accounts network_account indicates the account that owns the target network.

network_id

string

Unique identifier of the target network. For type=vpc virtual connections this is the CRN of the target VPC. This field does not apply to type=classic connections.

status

string

Status of the virtual connection.

The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

type

string

Virtual connection type.

The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

400 - An invalid template was provided.

errors

array

Array of errors

trace

object

unique identfier

404 - The specified gateway could not be found.

errors

array

Array of errors

trace

object

unique identfier

Delete virtual connection

DELETE /gateways/{gateway_id}/virtual_connections/{id}

Delete the virtual connection.

Request

Response

204 - The virtual connection was removed successfully.

404 - A virtual connection with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Get virtual connection

GET /gateways/{gateway_id}/virtual_connections/{id}

Retrieve a virtual connection.

Request

Response

200 - The virtual connection was retrieved successfully.

created_at

string

The date and time resource was created

id

object

unique identifier

name

string

network_account

string

For virtual connections across two different IBM Cloud Accounts network_account indicates the account that owns the target network.

network_id

string

Unique identifier of the target network. For type=vpc virtual connections this is the CRN of the target VPC. This field does not apply to type=classic connections.

status

string

Status of the virtual connection.

The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

type

string

Virtual connection type.

The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

404 - A virtual connection with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Update virtual connection

PATCH /gateways/{gateway_id}/virtual_connections/{id}

Update a virtual connection.

Request

Request Body

The virtual connection patch template

Response

200 - The virtual connection was updated successfully.

created_at

string

The date and time resource was created

id

object

unique identifier

name

string

network_account

string

For virtual connections across two different IBM Cloud Accounts network_account indicates the account that owns the target network.

network_id

string

Unique identifier of the target network. For type=vpc virtual connections this is the CRN of the target VPC. This field does not apply to type=classic connections.

status

string

Status of the virtual connection.

The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

type

string

Virtual connection type.

The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

400 - The request was invalid.

errors

array

Array of errors

trace

object

unique identfier

404 - A virtual connection with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Delete gateway

DELETE /gateways/{id}

Delete a Direct Link gateway.

Request

Response

204 - The Direct Link gateway was deleted successfully.

400 - The gateway could not be deleted as there are virtual connections associated with it. Delete all virtual connections associated with this gateway and retry.

errors

array

Array of errors

trace

object

unique identfier

404 - A Direct Link gateway with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Get gateway

GET /gateways/{id}

Retrieve a Direct Link gateway.

Request

Response

200 - The Direct Link gateway was retrieved successfully.

404 - A Direct Link gateway with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Update gateway

PATCH /gateways/{id}

Update a Direct Link gateway.

Request

Request Body

The Direct Link gateway patch

Response

200 - The Direct Link gateway was updated successfully.

as_prepends

array

array of AS Prepend information.

authentication_key

AuthenticationKeyReference

bfd_config

GatewayBfdConfig

BFD configuration information.

bgp_asn

integer

Customer BGP ASN

bgp_base_cidr

string

(DEPRECATED) BGP base CIDR is deprecated and no longer recognized by the Direct Link APIs.

See bgp_cer_cidr and bgp_ibm_cidr fields instead for IP related information.

Deprecated field bgp_base_cidr will be removed from the API specification after 15-MAR-2021.

bgp_cer_cidr

string

BGP customer edge router CIDR

bgp_ibm_asn

integer

IBM BGP ASN

bgp_ibm_cidr

string

BGP IBM CIDR

bgp_status

string

Gateway BGP status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

bgp_status_updated_at

string

Date and time bgp status was updated

carrier_name

string

Carrier name. Only set for type=dedicated gateways.

change_request

object

Changes pending approval for provider managed Direct Link Connect gateways.

completion_notice_reject_reason

string

Reason for completion notice rejection. Only included on type=dedicated gateways with a rejected completion notice.

connection_mode

string

created_at

string

The date and time resource was created

crn

string

The CRN (Cloud Resource Name) of this gateway

cross_account

boolean

Indicates whether this gateway is cross account gateway.

cross_connect_router

string

Cross connect router. Only included on type=dedicated gateways.

customer_name

string

Customer name. Only set for type=dedicated gateways.

default_export_route_filter

string

The default directional route filter action that applies to routes that do not match any directional route filters.

default_import_route_filter

string

The default directional route filter action that applies to routes that do not match any directional route filters.

global

boolean

Gateways with global routing (`true`) can connect to networks outside their associated region.

id

string

The unique identifier of this gateway

link_status

string

link_status_updated_at

string

Date and time link status was updated

location_display_name

string

Gateway location long name

location_name

string

Gateway location

macsec

GatewayMacsecReference

MACsec configuration information of a direct link.

macsec_capability

GatewayMacsecCapability

Indicates the direct link's MACsec capability. It must match one of the MACsec related `capabilities` of the `cross_connect_router`.

Only included on type=dedicated direct links.

`non_macsec`: The direct link does not support MACsec.
`macsec`: The direct link supports MACsec. The MACsec feature must be enabled.
`macsec_optional`: The direct link supports MACsec. The MACsec feature is not required and can be enabled after direct link creation.

metered

boolean

Metered billing option. When `true` gateway usage is billed per gigabyte. When `false` there is no per gigabyte usage charge, instead a flat rate is charged for the gateway.

name

string

The unique user-defined name for this gateway.

operational_status

string

Gateway operational status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

See `operational_status_reasons[]` for possible remediation of the `failed` `operational_status`.

operational_status_reasons

array

Context for certain values of `operational_status`.

patch_panel_completion_notice

string

Gateway patch panel complete notification from implementation team

port

GatewayPortReference

Port information for type=connect gateways.

provider_api_managed

boolean

Indicates whether gateway changes must be made via a provider portal.

resource_group

ResourceGroupReference

Resource group reference

speed_mbps

integer

Gateway speed in megabits per second

type

string

Offering type. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

vlan

integer

VLAN configured for this gateway. If there is no vlan configured for the gateway, the vlan will be absent. This property will also be absent if this gateway's `crn` is in another account.

400 - The request was invalid.

errors

array

Array of errors

trace

object

unique identfier

404 - A Direct Link gateway with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Approve or reject change requests

POST /gateways/{id}/actions

Approve or reject a gateway's current oustanding change request.

This API is only used for provider created Direct Link Connect gateways to approve or reject specific changes initiated from a provider portal.

Request

Request Body

GatewayActionTemplate

action

string

Action request

as_prepends

array

Applicable for create_gateway_approve requests to create AS Prepends. Contains an array of AS Prepend configuration information.

authentication_key

AuthenticationKeyIdentity

bfd_config

GatewayBfdConfigActionTemplate

Applicable for create_gateway_approve requests to select the gateway's BFD configuration information.

interval

Required *

integer

Minimum interval in milliseconds at which the local routing device transmits hello packets and then expects to receive a reply from a neighbor with which it has established a BFD session.

multiplier

integer

The number of hello packets not received by a neighbor that causes the originating interface to be declared down.

connection_mode

string

Applicable for create_gateway_approve requests to select the type of services this gateway is attached to. Mode transit indicates this gateway will be attached to Transit Gateway Service and direct means this gateway will be attached to vpc or classic connection. If unspecified on create_gateway_approve, default value direct is used. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

default_export_route_filter

object

The default directional route filter action that applies to routes that do not match any directional route filters.

default_import_route_filter

object

The default directional route filter action that applies to routes that do not match any directional route filters.

export_route_filters

RouteFilterCollectionTemplate

global

boolean

Applicable for create_gateway_approve requests to select the gateway's routing option. Gateways with global routing (`true`) can connect to networks outside of their associated region.

import_route_filters

RouteFilterCollectionTemplate

metered

boolean

Applicable for create_gateway_approve requests to select the gateway's metered billing option. When `true` gateway usage is billed per gigabyte. When `false` there is no per gigabyte usage charge, instead a flat rate is charged for the gateway.

resource_group

object

Set for create_gateway_approve requests to select the gateway's resource group. If unspecified on create_gateway_approve, the account's default resource group is used.

id

Required *

object

Resource group ID.

updates

array

Specify attribute updates being approved or rejected, update_attributes_approve and update_attributes_reject actions must provide an updates field that matches the gateway's current pending changes.

Response

200 - action successfully completed

as_prepends

array

array of AS Prepend information.

authentication_key

AuthenticationKeyReference

bfd_config

GatewayBfdConfig

BFD configuration information.

bgp_asn

integer

Customer BGP ASN

bgp_base_cidr

string

(DEPRECATED) BGP base CIDR is deprecated and no longer recognized by the Direct Link APIs.

See bgp_cer_cidr and bgp_ibm_cidr fields instead for IP related information.

Deprecated field bgp_base_cidr will be removed from the API specification after 15-MAR-2021.

bgp_cer_cidr

string

BGP customer edge router CIDR

bgp_ibm_asn

integer

IBM BGP ASN

bgp_ibm_cidr

string

BGP IBM CIDR

bgp_status

string

Gateway BGP status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

bgp_status_updated_at

string

Date and time bgp status was updated

carrier_name

string

Carrier name. Only set for type=dedicated gateways.

change_request

object

Changes pending approval for provider managed Direct Link Connect gateways.

completion_notice_reject_reason

string

Reason for completion notice rejection. Only included on type=dedicated gateways with a rejected completion notice.

connection_mode

string

created_at

string

The date and time resource was created

crn

string

The CRN (Cloud Resource Name) of this gateway

cross_account

boolean

Indicates whether this gateway is cross account gateway.

cross_connect_router

string

Cross connect router. Only included on type=dedicated gateways.

customer_name

string

Customer name. Only set for type=dedicated gateways.

default_export_route_filter

string

The default directional route filter action that applies to routes that do not match any directional route filters.

default_import_route_filter

string

The default directional route filter action that applies to routes that do not match any directional route filters.

global

boolean

Gateways with global routing (`true`) can connect to networks outside their associated region.

id

string

The unique identifier of this gateway

link_status

string

link_status_updated_at

string

Date and time link status was updated

location_display_name

string

Gateway location long name

location_name

string

Gateway location

macsec

GatewayMacsecReference

MACsec configuration information of a direct link.

macsec_capability

GatewayMacsecCapability

Indicates the direct link's MACsec capability. It must match one of the MACsec related `capabilities` of the `cross_connect_router`.

Only included on type=dedicated direct links.

`non_macsec`: The direct link does not support MACsec.
`macsec`: The direct link supports MACsec. The MACsec feature must be enabled.
`macsec_optional`: The direct link supports MACsec. The MACsec feature is not required and can be enabled after direct link creation.

metered

boolean

Metered billing option. When `true` gateway usage is billed per gigabyte. When `false` there is no per gigabyte usage charge, instead a flat rate is charged for the gateway.

name

string

The unique user-defined name for this gateway.

operational_status

string

Gateway operational status. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

See `operational_status_reasons[]` for possible remediation of the `failed` `operational_status`.

operational_status_reasons

array

Context for certain values of `operational_status`.

patch_panel_completion_notice

string

Gateway patch panel complete notification from implementation team

port

GatewayPortReference

Port information for type=connect gateways.

provider_api_managed

boolean

Indicates whether gateway changes must be made via a provider portal.

resource_group

ResourceGroupReference

Resource group reference

speed_mbps

integer

Gateway speed in megabits per second

type

string

Offering type. The list of enumerated values for this property may expand in the future. Code and processes using this field must tolerate unexpected values.

vlan

integer

VLAN configured for this gateway. If there is no vlan configured for the gateway, the vlan will be absent. This property will also be absent if this gateway's `crn` is in another account.

204 - action successfully completed

400 - invalid request

errors

array

Array of errors

trace

object

unique identfier

403 - request not authorized

errors

array

Array of errors

trace

object

unique identfier

404 - resource not found

errors

array

Array of errors

trace

object

unique identfier

Get completion notice

GET /gateways/{id}/completion_notice

Retrieve a Direct Link Dedicated gateway's completion notice.

Request

Response

200 - Completion notice retrieved successfully.

404 - The Direct Link completion notice for the specified gateway could not be found.

errors

array

Array of errors

trace

object

unique identfier

Create completion notice

PUT /gateways/{id}/completion_notice

Upload a Direct Link Dedicated gateway completion notice.

Request

Request Body

Completion notice PDF file

Response

204 - Completion notice upload successful.

400 - An invalid Direct Link completion notice request was provided.

errors

array

Array of errors

trace

object

unique identfier

404 - The Direct Link completion notice for the specified gateway could not be found.

errors

array

Array of errors

trace

object

unique identfier

Get letter of authorization

GET /gateways/{id}/letter_of_authorization

Retrieve a Direct Link Dedicated gateway's Letter of Authorization.

Request

Response

200 - Letter of Authorization retrieved successfully.

404 - Letter of authorization not found.

errors

array

Array of errors

trace

object

unique identfier

Unset MACsec configuration

DELETE /gateways/{id}/macsec

Removes the MACsec configuration from a direct link, disabling the features.

Request

Response

204 - The MACsec configuration was unset successfully.

400 - The direct link's `macsec_capability` does not allow deletion of MACsec.

errors

array

Array of errors

trace

object

unique identfier

404 - No MACsec configuration set for the direct link.

errors

array

Array of errors

trace

object

unique identfier

Get MACsec configuration

GET /gateways/{id}/macsec

Retrieve the MACsec configuration of a direct link.

Request

Response

200 - The MACsec configuration of the direct link was retrieved successfully.

active

boolean

Indicates if the MACsec feature is currently active (true) or inactive (false) for a direct link.

cipher_suite

string

The cipher suite used in generating the security association key (SAK).

confidentiality_offset

integer

The confidentiality offset determines the number of octets in an Ethernet frame that are not encrypted.

created_at

string

The date and time the resource was created

key_server_priority

integer

Used in the MACsec Key Agreement (MKA) protocol to determine which peer acts as the key server.

Lower values indicate a higher preference to be the key server.

The MACsec configuration on the direct link will always set this value to 255.

sak_rekey

SakRekey

Determines how SAK rekeying occurs. It is either timer based or based on the amount of used packet numbers.

security_policy

string

Determines how packets without MACsec headers are handled.

`must_secure` - Packets without MACsec headers are dropped. Use this policy to prefer security over network availability.
`should_secure` - Packets without MACsec headers are allowed. Use this policy to prefer network availability over security.

status

string

Current status of MACsec on this direct link.

Status `offline` is returned when MACsec is inactive and during direct link creation.

Status `deleting` is returned when MACsec during removal of MACsec from the direct link and during direct link deletion.

See `status_reasons[]` for possible remediation of the `failed` `status`.

status_reasons

array

Context for certain values of `status`.

updated_at

string

The date and time the resource was last updated

window_size

integer

The window size determines the number of frames in a window for replay protection.

Replay protection is used to counter replay attacks. Frames within a window size can be out of order and are not replay protected.

404 - A direct link with the specified identifier could not be found or no MACsec configuration set for the direct link.

errors

array

Array of errors

trace

object

unique identfier

Update MACsec configuration

PATCH /gateways/{id}/macsec

Updates the MACsec configuration on a direct link.

Request

Request Body

The MACsec configuration patch.

Response

200 - The MACsec configuration of the direct link was updated successfully.

active

boolean

Indicates if the MACsec feature is currently active (true) or inactive (false) for a direct link.

cipher_suite

string

The cipher suite used in generating the security association key (SAK).

confidentiality_offset

integer

The confidentiality offset determines the number of octets in an Ethernet frame that are not encrypted.

created_at

string

The date and time the resource was created

key_server_priority

integer

Used in the MACsec Key Agreement (MKA) protocol to determine which peer acts as the key server.

Lower values indicate a higher preference to be the key server.

The MACsec configuration on the direct link will always set this value to 255.

sak_rekey

SakRekey

Determines how SAK rekeying occurs. It is either timer based or based on the amount of used packet numbers.

security_policy

string

Determines how packets without MACsec headers are handled.

`must_secure` - Packets without MACsec headers are dropped. Use this policy to prefer security over network availability.
`should_secure` - Packets without MACsec headers are allowed. Use this policy to prefer network availability over security.

status

string

Current status of MACsec on this direct link.

Status `offline` is returned when MACsec is inactive and during direct link creation.

Status `deleting` is returned when MACsec during removal of MACsec from the direct link and during direct link deletion.

See `status_reasons[]` for possible remediation of the `failed` `status`.

status_reasons

array

Context for certain values of `status`.

updated_at

string

The date and time the resource was last updated

window_size

integer

The window size determines the number of frames in a window for replay protection.

Replay protection is used to counter replay attacks. Frames within a window size can be out of order and are not replay protected.

400 - The request was invalid.

errors

array

Array of errors

trace

object

unique identfier

404 - A direct link with the specified identifier could not be found or no MACsec configuration set for the direct link.

errors

array

Array of errors

trace

object

unique identfier

Set MACsec configuration

PUT /gateways/{id}/macsec

Sets the MACsec configuration on a direct link, enabling the feature.

Request

Request Body

GatewayMacsecPrototype

The MACsec configuration prototype.

active

Required *

boolean

Determines if the MACsec feature will initially be active (true) or inactive (false) for a direct link.

caks

Required *

array

List of all connectivity association keys (CAKs) to be associated associated with the MACsec feature on a direct link.

There must be at least one CAK with `session`: `primary`. There can be at most one CAK with `session`: `fallback`

All CAKs must reference a unique key.

sak_rekey

Required *

SakRekeyPrototype

Determines how SAK rekeying occurs. It is either timer based or based on the amount of used packet numbers.

security_policy

Required *

string

Determines how packets without MACsec headers are handled.

`must_secure` - Packets without MACsec headers are dropped. Use this policy to prefer security over network availability.
`should_secure` - Packets without MACsec headers are allowed. Use this policy to prefer network availability over security.

window_size

integer

The window size determines the number of frames in a window for replay protection.

Replay protection is used to counter replay attacks. Frames within a window size can be out of order and are not replay protected.

Path Parameters

Query Parameters

Response

200 - The MACsec configuration of the direct link was already set.

active

boolean

Indicates if the MACsec feature is currently active (true) or inactive (false) for a direct link.

cipher_suite

string

The cipher suite used in generating the security association key (SAK).

confidentiality_offset

integer

The confidentiality offset determines the number of octets in an Ethernet frame that are not encrypted.

created_at

string

The date and time the resource was created

key_server_priority

integer

Used in the MACsec Key Agreement (MKA) protocol to determine which peer acts as the key server.

Lower values indicate a higher preference to be the key server.

The MACsec configuration on the direct link will always set this value to 255.

sak_rekey

SakRekey

Determines how SAK rekeying occurs. It is either timer based or based on the amount of used packet numbers.

security_policy

string

Determines how packets without MACsec headers are handled.

`must_secure` - Packets without MACsec headers are dropped. Use this policy to prefer security over network availability.
`should_secure` - Packets without MACsec headers are allowed. Use this policy to prefer network availability over security.

status

string

Current status of MACsec on this direct link.

Status `offline` is returned when MACsec is inactive and during direct link creation.

Status `deleting` is returned when MACsec during removal of MACsec from the direct link and during direct link deletion.

See `status_reasons[]` for possible remediation of the `failed` `status`.

status_reasons

array

Context for certain values of `status`.

updated_at

string

The date and time the resource was last updated

window_size

integer

The window size determines the number of frames in a window for replay protection.

Replay protection is used to counter replay attacks. Frames within a window size can be out of order and are not replay protected.

201 - The MACsec configuration of the direct link was set successfully.

active

boolean

Indicates if the MACsec feature is currently active (true) or inactive (false) for a direct link.

cipher_suite

string

The cipher suite used in generating the security association key (SAK).

confidentiality_offset

integer

The confidentiality offset determines the number of octets in an Ethernet frame that are not encrypted.

created_at

string

The date and time the resource was created

key_server_priority

integer

Used in the MACsec Key Agreement (MKA) protocol to determine which peer acts as the key server.

Lower values indicate a higher preference to be the key server.

The MACsec configuration on the direct link will always set this value to 255.

sak_rekey

SakRekey

Determines how SAK rekeying occurs. It is either timer based or based on the amount of used packet numbers.

security_policy

string

Determines how packets without MACsec headers are handled.

`must_secure` - Packets without MACsec headers are dropped. Use this policy to prefer security over network availability.
`should_secure` - Packets without MACsec headers are allowed. Use this policy to prefer network availability over security.

status

string

Current status of MACsec on this direct link.

Status `offline` is returned when MACsec is inactive and during direct link creation.

Status `deleting` is returned when MACsec during removal of MACsec from the direct link and during direct link deletion.

See `status_reasons[]` for possible remediation of the `failed` `status`.

status_reasons

array

Context for certain values of `status`.

updated_at

string

The date and time the resource was last updated

window_size

integer

The window size determines the number of frames in a window for replay protection.

Replay protection is used to counter replay attacks. Frames within a window size can be out of order and are not replay protected.

400 - The request was invalid.

errors

array

Array of errors

trace

object

unique identfier

404 - A direct link with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

List MACsec CAKs

GET /gateways/{id}/macsec/caks

List the CAKs associated with the MACsec configuration of a direct link.

Request

Response

200 - The list of CAKs was retrieved successfully.

caks

array

List of all connectivity association keys (CAKs) associated with the MACsec feature on a direct link.

404 - A direct link with the specified identifier could not be found or no MACsec configuration set for the direct link.

errors

array

Array of errors

trace

object

unique identfier

Create MACsec CAK

POST /gateways/{id}/macsec/caks

Creates a CAK associated with the MACsec configuration of a direct link.

Request

Request Body

GatewayMacsecCakPrototype

The MACsec CAK prototype.

key

Required *

GatewayMacsecCakKeyIdentity

name

Required *

string

The name identifies the connectivity association key (CAK) within the MACsec key chain.

The CAK's `name` must be a hexadecimal string of even lengths between 2 to 64 inclusive.

This value, along with the material of the `key`, must match on the MACsec peers.

session

Required *

string

The intended session the key will be used to secure.

If the `primary` MACsec session fails due to a key/key name mismatch on the peers, the `fallback` session can take over.

There must be a `primary` session CAK. A `fallback` CAK is optional.

Response

201 - MACsec CAK successfully created.

active_delta

GatewayMacsecCakActiveDelta

This field will be present when the `status` of the MACsec CAK is `rotating` or `inactive`. It might be present when the CAK `status` is `failed`.

This object denotes the MACsec CAK's values prior to beginning a CAK rotation and represents the previous key still configured in the direct link's MACsec key chain.

This object will be removed when the MACsec CAK rotation completes, indicating that the previous key has been removed from the key chain, and the current CAK's values are in use.

created_at

string

The date and time the resource was created

id

string

The unique identifier for this connectivity association key (CAK).

key

GatewayMacsecCakKeyReference

name

string

The name identifies the connectivity association key (CAK) within the MACsec key chain.

The CAK's `name` must be a hexadecimal string of even lengths between 2 to 64 inclusive.

This value, along with the material of the `key`, must match on the MACsec peers.

session

string

The intended session the key will be used to secure.

If the `primary` MACsec session fails due to a key/key name mismatch on the peers, the `fallback` session can take over.

There must be a `primary` session CAK. A `fallback` CAK is optional.

status

string

Current status of the CAK.

Status `operational` is returned when the CAK is configured successfully.

Status `rotating` is returned during a key rotation. The CAK defined by `active_delta` is still configured on the device and could be securing the MACsec session. In the case of a primary CAK, the status will be `rotating` for a period of time while waiting for the MACsec session to be secured with the new CAK. After that time, the CAK will either enter `active` or `inactive` status.

Status `active` is returned when the CAK is configured successfully and is currently used to secure the MACsec session.

Status `inactive` is returned when the CAK is configured successfully, but is not currently used to secure the MACsec session. The CAK might enter `rotating` status, and ultimately the `active` status, if it is found to be used to secure the MACsec session. The CAK might never leave this status on its own (e.g. if there is a key/key name mismatch). You are allowed to patch the CAK in this state to start the rotation procedure again.

Status `failed` is returned when the CAK cannot be configured. To recover, first resolve any issues with your HPCS key, then patch this CAK with the same or new key. Alternatively, you can delete this CAK if used for the `fallback` session.

updated_at

string

The date and time the resource was last updated

400 - The request was invalid.

errors

array

Array of errors

trace

object

unique identfier

404 - A direct link with the specified identifier could not be found or no MACsec configuration set for the direct link.

errors

array

Array of errors

trace

object

unique identfier

Delete MACsec CAK

DELETE /gateways/{id}/macsec/caks/{cak_id}

Deletes the CAK from the MACsec configuration of a direct link.

Request

Response

204 - The MACsec CAK was deleted successfully.

400 - Cannot delete primary CAK, MACsec configuration must have a valid primary CAK

errors

array

Array of errors

trace

object

unique identfier

404 - A direct link with the specified identifier could not be found or no MACsec configuration set for the direct link or a MACsec CAK with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Get MACsec CAK

GET /gateways/{id}/macsec/caks/{cak_id}

Get a MACsec CAK by its identifier.

Request

Response

200 - The MACsec CAK was retrieved successfully.

active_delta

GatewayMacsecCakActiveDelta

This field will be present when the `status` of the MACsec CAK is `rotating` or `inactive`. It might be present when the CAK `status` is `failed`.

This object denotes the MACsec CAK's values prior to beginning a CAK rotation and represents the previous key still configured in the direct link's MACsec key chain.

This object will be removed when the MACsec CAK rotation completes, indicating that the previous key has been removed from the key chain, and the current CAK's values are in use.

created_at

string

The date and time the resource was created

id

string

The unique identifier for this connectivity association key (CAK).

key

GatewayMacsecCakKeyReference

name

string

The name identifies the connectivity association key (CAK) within the MACsec key chain.

The CAK's `name` must be a hexadecimal string of even lengths between 2 to 64 inclusive.

This value, along with the material of the `key`, must match on the MACsec peers.

session

string

The intended session the key will be used to secure.

If the `primary` MACsec session fails due to a key/key name mismatch on the peers, the `fallback` session can take over.

There must be a `primary` session CAK. A `fallback` CAK is optional.

status

string

Current status of the CAK.

Status `operational` is returned when the CAK is configured successfully.

Status `active` is returned when the CAK is configured successfully and is currently used to secure the MACsec session.

updated_at

string

The date and time the resource was last updated

404 - A direct link with the specified identifier could not be found or no MACsec configuration set for the direct link or a MACsec CAK with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Update MACsec CAK

PATCH /gateways/{id}/macsec/caks/{cak_id}

Updates the CAK on the MACsec configuration of a direct link.

Request

Request Body

The MACsec CAK patch.

Response

200 - The MACsec CAK was updated successfully.

active_delta

GatewayMacsecCakActiveDelta

This field will be present when the `status` of the MACsec CAK is `rotating` or `inactive`. It might be present when the CAK `status` is `failed`.

This object denotes the MACsec CAK's values prior to beginning a CAK rotation and represents the previous key still configured in the direct link's MACsec key chain.

This object will be removed when the MACsec CAK rotation completes, indicating that the previous key has been removed from the key chain, and the current CAK's values are in use.

created_at

string

The date and time the resource was created

id

string

The unique identifier for this connectivity association key (CAK).

key

GatewayMacsecCakKeyReference

name

string

The name identifies the connectivity association key (CAK) within the MACsec key chain.

The CAK's `name` must be a hexadecimal string of even lengths between 2 to 64 inclusive.

This value, along with the material of the `key`, must match on the MACsec peers.

session

string

The intended session the key will be used to secure.

If the `primary` MACsec session fails due to a key/key name mismatch on the peers, the `fallback` session can take over.

There must be a `primary` session CAK. A `fallback` CAK is optional.

status

string

Current status of the CAK.

Status `operational` is returned when the CAK is configured successfully.

Status `active` is returned when the CAK is configured successfully and is currently used to secure the MACsec session.

updated_at

string

The date and time the resource was last updated

400 - The request was invalid.

errors

array

Array of errors

trace

object

unique identfier

404 - A direct link with the specified identifier could not be found or no MACsec configuration set for the direct link or a MACsec CAK with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

Gateway statistics/debug information

GET /gateways/{id}/statistics

Retrieve gateway statistics or debug information. Specify statistic to retrieve using required `type` query parameter.

Request

Path Parameters

id

Required *

Direct Link gateway identifier

Query Parameters

type

Required *

string

Specify statistic to retrieve

version

Required *

string

Requests the version of the API as a date in the format `YYYY-MM-DD`. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

Response

200 - action successfully completed

statistics

array

Collection of gateway statistics

403 - request not authorized

errors

array

Array of errors

trace

object

unique identfier

404 - resource not found

errors

array

Array of errors

trace

object

unique identfier

errors

array

Array of errors

trace

object

unique identfier

Gateway status information

GET /gateways/{id}/status

Retrieve gateway status. Specify status to retrieve using required `type` query parameter.

Request

Response

200 - action successfully completed

status

array

array of status

403 - request not authorized

errors

array

Array of errors

trace

object

unique identfier

404 - resource not found

errors

array

Array of errors

trace

object

unique identfier

409 - BFD must be active to retrieve BFD status

errors

array

Array of errors

trace

object

unique identfier

List available locations

GET /offering_types/{offering_type}/locations

Retrieve the list of valid locations for the specified Direct Link offering.

Request

Path Parameters

offering_type

Required *

string

The Direct Link offering type. Current supported values are `"dedicated"` and `"connect"`.

Query Parameters

version

Required *

string

Requests the version of the API as a date in the format `YYYY-MM-DD`. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

Response

200 - The Direct Link locations for offering type were retrieved successfully.

locations

array

Collection of Direct Link locations

400 - The Direct Link locations offering type could not be retrieved.

errors

array

Array of errors

trace

object

unique identfier

404 - A Direct Link locations for the specified offering type could not be found.

errors

array

Array of errors

trace

object

unique identfier

List routers

GET /offering_types/{offering_type}/locations/{location_name}/cross_connect_routers

Retrieve location specific cross connect router information. Only valid for offering_type=dedicated locations.

Request

Path Parameters

offering_type

Required *

string

The Direct Link offering type. Current supported values are `"dedicated"` and `"connect"`.

location_name

Required *

string

The name of the Direct Link location

Query Parameters

version

Required *

string

Requests the version of the API as a date in the format `YYYY-MM-DD`. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

Response

200 - The location information was retrieved successfully.

cross_connect_routers

array

Array of Routers for this location

404 - A location information with the specified identifier could not be found.

errors

array

Array of errors

trace

object

unique identfier

List speed options

GET /offering_types/{offering_type}/speeds

List the available Direct Link speeds.

Request

Path Parameters

offering_type

Required *

string

The Direct Link offering type. Current supported values are `"dedicated"` and `"connect"`.

Query Parameters

version

Required *

string

Requests the version of the API as a date in the format `YYYY-MM-DD`. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

Response

200 - The Direct Link offering speeds were retrieved successfully.

speeds

array

speed list

400 - The Direct Link offering speeds could not be retrieved for the offering type.

errors

array

Array of errors

trace

object

unique identfier

404 - A Direct Link offering speed with the specified offering type could not be found.

errors

array

Array of errors

trace

object

unique identfier

List ports

GET /ports

Retrieve list of available Direct Link connect ports. These ports can be used to create Direct Link connect gateways.

Request

Path Parameters

Query Parameters

version

Required *

string

Requests the version of the API as a date in the format `YYYY-MM-DD`. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

start

string

A server-supplied token determining which resource to start the page on

limit

integer

The number of resources to return on a page

location_name

string

Direct Link location short name

Response

200 - Ports retrieved successfully.

first

object

A reference to the first page of resources

limit

integer

The maximum number of resources can be returned by the request

object

A reference to the next page of resources; this reference is included for all pages except the last page

total_count

integer

The total number of resources across all pages

ports

array

Array of ports

404 - Port information could not be found.

errors

array

Array of errors

trace

object

unique identfier

Get port

GET /ports/{id}

Retrieve Direct Link Connect provider port.

Request

Path Parameters

id

Required *

The port identifier

Query Parameters

version

Required *

string

Requests the version of the API as a date in the format `YYYY-MM-DD`. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

Response

200 - Port retrieved successfully.

direct_link_count

integer

Count of existing Direct Link gateways in this account on this port.

id

string

Port identifier

label

string

Port Label

location_display_name

string

Port location long name

location_name

string

Port location name identifier

provider_name

string

Port's provider name

supported_link_speeds

array

Port's supported speeds in megabits per second

404 - Port not be found.

errors

array

Array of errors

trace

object

unique identfier