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
Parameters
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
Parameters
gateway_template
Required *
GatewayTemplate
The Direct Link Gateway template.
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
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.
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
if_match
Required *
str
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Example: W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Constraints:
- Min length: 2
- Max length: 512
- Pattern:
/(?:W\/)?\"(?:[ !#-\\x7E\\x80-\\xFF]*|\\r\\n[\\t ]|\\\\.)*\"/
as_prepends
List[AsPrependPrefixArrayTemplate]
array of AS Prepend configuration information.
Constraints:
- Max items: 50
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
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
Response
200 - Export route filters retrieved successfully.
export_route_filters
array
Array of export route filters
404 -
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
action
Required *
str
Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter.
Example: permit
Allowed values: permit, deny
prefix
Required *
str
IP prefix representing an address and mask length of the prefix-set.
Example: 192.168.100.0/24
Constraints:
- Min length: 7
- Max length: 18
- Pattern:
/^([0-9]{1,3}\\.){3}[0-9]{1,3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$/
before
str
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.
Example: 1a15dcab-7e40-45e1-b7c5-bc690eaa9782
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
ge
int
The minimum matching length of the prefix-set (mnemonic for greater than or equal to).
Example: 25
le
int
The maximum matching length of the prefix-set (mnemonic for less than or equal to).
Example: 30
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
if_match
Required *
str
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Example: W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Constraints:
- Min length: 2
- Max length: 512
- Pattern:
/(?:W\/)?\"(?:[ !#-\\x7E\\x80-\\xFF]*|\\r\\n[\\t ]|\\\\.)*\"/
export_route_filters
List[GatewayTemplateRouteFilter]
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.
Constraints:
- Max items: 100
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
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Identifier of an import route filter.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Identifier of an import route filter.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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 -
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Identifier of an import route filter.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
update_route_filter_template
Required *
UpdateRouteFilterTemplate
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 -
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
Response
200 - Import route filters retrieved successfully.
import_route_filters
array
Array of import route filters
404 -
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.
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
action
Required *
str
Determines whether routes that match the prefix-set will be allowed (permit) or rejected (deny) through the filter.
Example: permit
Allowed values: permit, deny
prefix
Required *
str
IP prefix representing an address and mask length of the prefix-set.
Example: 192.168.100.0/24
Constraints:
- Min length: 7
- Max length: 18
- Pattern:
/^([0-9]{1,3}\\.){3}[0-9]{1,3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$/
before
str
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.
Example: 1a15dcab-7e40-45e1-b7c5-bc690eaa9782
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
ge
int
The minimum matching length of the prefix-set (mnemonic for greater than or equal to).
Example: 25
le
int
The maximum matching length of the prefix-set (mnemonic for less than or equal to).
Example: 30
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
if_match
Required *
str
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Example: W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Constraints:
- Min length: 2
- Max length: 512
- Pattern:
/(?:W\/)?\"(?:[ !#-\\x7E\\x80-\\xFF]*|\\r\\n[\\t ]|\\\\.)*\"/
import_route_filters
List[GatewayTemplateRouteFilter]
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.
Constraints:
- Max items: 100
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
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Identifier of an import route filter.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Identifier of an import route filter.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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 -
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.
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Identifier of an import route filter.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
update_route_filter_template
Required *
UpdateRouteFilterTemplate
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Route report identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
Route report identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
name
Required *
str
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.
Example: newVC
Constraints:
- Min length: 1
- Max length: 63
- Pattern:
/^([a-zA-Z]|[a-zA-Z][-_a-zA-Z0-9]*[a-zA-Z0-9])$/
type
Required *
str
The type of virtual connection.
Example: vpc
Allowed values: classic, vpc
network_id
str
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.
Example: crn:v1:bluemix:public:is:us-east:a/28e4d90ac7504be69447111122223333::vpc:aaa81ac8-5e96-42a0-a4b7-6c2e2d1bbbbb
Response
201 - The virtual connection was created successfully.
created_at
string
The date and time resource was created
id
object
unique identifier
name
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_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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
The virtual connection identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
The virtual connection identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
Response
200 - The virtual connection was retrieved successfully.
created_at
string
The date and time resource was created
id
object
unique identifier
name
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_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
Parameters
gateway_id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
id
Required *
str
The virtual connection identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
gateway_virtual_connection_patch_template
Required *
GatewayVirtualConnectionPatchTemplate
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
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_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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
gateway_patch_template
Required *
GatewayPatchTemplate
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
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.
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 - 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
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
Parameters
id
Required *
str
Direct Link Connect gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
action
str
Action request.
Allowed values: create_gateway_approve, create_gateway_reject, delete_gateway_approve, delete_gateway_reject, update_attributes_approve, update_attributes_reject
as_prepends
List[AsPrependTemplate]
Applicable for create_gateway_approve requests to create AS Prepends. Contains an array of AS Prepend configuration information.
Constraints:
- Max items: 50
authentication_key
AuthenticationKeyIdentity
bfd_config
GatewayBfdConfigActionTemplate
Applicable for create_gateway_approve requests to select the gateway's BFD configuration information.
connection_mode
str
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.
Example: transit
Allowed values: direct, transit
Default: direct
default_export_route_filter
str
The default directional route filter action that applies to routes that do not match any directional route filters.
Example: permit
Allowed values: permit, deny
Default: permit
default_import_route_filter
str
The default directional route filter action that applies to routes that do not match any directional route filters.
Example: permit
Allowed values: permit, deny
Default: permit
export_route_filters
List[GatewayTemplateRouteFilter]
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.
Constraints:
- Max items: 100
global_
bool
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.
Example: true
import_route_filters
List[GatewayTemplateRouteFilter]
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.
Constraints:
- Max items: 100
metered
bool
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.
Example: false
resource_group
ResourceGroupIdentity
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.
updates
List[GatewayActionTemplateUpdatesItem]
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
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.
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.
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
Parameters
id
Required *
str
Direct Link Dedicated gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
id
Required *
str
Direct Link Dedicated gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
upload
BinaryIO
Completion notice PDF file.
upload_content_type
str
The content type of upload.
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
Unset MACsec configuration
DELETE /gateways/{id}/macsec
Removes the MACsec configuration from a direct link, disabling the features.
Request
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
gateway_macsec_patch
Required *
GatewayMacsecPatch
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
active
Required *
bool
Determines if the MACsec feature will initially be active (true) or inactive (false) for a direct link.
Example: true
caks
Required *
List[GatewayMacsecCakPrototype]
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.
Constraints:
- Min items: 1
- Max items: 4
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 *
str
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.
Example: must_secure
Allowed values: must_secure, should_secure
window_size
int
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.
Example: 64
Default: 512
if_match
str
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
`If-Match` is required when the resource exists and has an ETag value.
Example: W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Constraints:
- Min length: 2
- Max length: 512
- Pattern:
/(?:W\/)?\"(?:[ !#-\\x7E\\x80-\\xFF]*|\\r\\n[\\t ]|\\\\.)*\"/
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
key
Required *
GatewayMacsecCakKeyIdentity
name
Required *
str
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.
Example: 1000
Constraints:
- Min length: 2
- Max length: 64
- Pattern:
/^([0-9a-fA-F]{2}){1,32}$/
session
Required *
str
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.
Allowed values: primary, fallback
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
cak_id
Required *
str
MACsec CAK identifier.
Example: ef4dcb1a-fee4-41c7-9e11-9cd99e65c1f4
Constraints:
- Max length: 128
- Pattern:
/^[-0-9a-z]+$/
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
cak_id
Required *
str
MACsec CAK identifier.
Example: ef4dcb1a-fee4-41c7-9e11-9cd99e65c1f4
Constraints:
- Max length: 128
- Pattern:
/^[-0-9a-z]+$/
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 `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
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
cak_id
Required *
str
MACsec CAK identifier.
Example: ef4dcb1a-fee4-41c7-9e11-9cd99e65c1f4
Constraints:
- Max length: 128
- Pattern:
/^[-0-9a-z]+$/
gateway_macsec_cak_patch
Required *
GatewayMacsecCakPatch
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 `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 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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
type
Required *
str
Specify statistic to retrieve.
Allowed values: macsec_mka_session, macsec_policy, macsec_mka_statistics, bfd_session
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
409 - MACsec must be active to retrieve MACsec related data
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
Parameters
id
Required *
str
Direct Link gateway identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
type
str
Specify status to retrieve.
Allowed values: bgp, bfd, link
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
Parameters
offering_type
Required *
str
The Direct Link offering type. Current supported values are `"dedicated"` and `"connect"`.
Example: dedicated
Allowed values: dedicated, connect
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
Parameters
offering_type
Required *
str
The Direct Link offering type. Current supported values are `"dedicated"` and `"connect"`.
Example: dedicated
Allowed values: dedicated, connect
location_name
Required *
str
The name of the Direct Link location.
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
Parameters
offering_type
Required *
str
The Direct Link offering type. Current supported values are `"dedicated"` and `"connect"`.
Example: dedicated
Allowed values: dedicated, connect
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
Parameters
start
str
A server-supplied token determining which resource to start the page on.
Constraints:
- Min length: 1
- Max length: 512
- Pattern:
/^[ -~]+$/
limit
int
The number of resources to return on a page.
Default: 50
location_name
str
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
next
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
Parameters
id
Required *
str
The port identifier.
Example: 0a06fb9b-820f-4c44-8a31-77f1f0806d28
Constraints:
- Min length: 36
- Max length: 36
- Pattern:
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
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