Skip to navigation
API ReferenceInterface

Retrieve Tenant-visible Interfaces

View as Markdown

Retrieve current, non-deleted REST Interfaces visible to the caller’s Tenant. Results include all Interfaces on the caller’s Instances, plus Interfaces on other Tenants’ Instances when they explicitly select a VPC owned by the caller or a VPC Prefix under one.

vpcId filters by the directly selected VPC or the parent of an explicitly selected VPC Prefix. crossTenant: true returns only Interfaces whose Instance and selected VPC or VPC Prefix have different owning Tenants; false returns only matching ownership. instanceTenantId filters by the Tenant that owns the consuming Instance, and vpcTenantId filters by the Tenant that owns the selected VPC or VPC Prefix. Filters compose and may produce an empty result. A valid but inaccessible vpcId, instanceTenantId, or vpcTenantId returns an empty list rather than disclosing resource existence.

The caller must have an organization membership and an authorization role with TENANT_ADMIN suffix. No cross-Tenant creation capability is required to list visible Interfaces. A cross-Tenant result includes non-null instanceTenantId and vpcTenantId; both are null when the owners match. The response uses the complete Interface representation, including addresses and routing data. Visibility does not grant authority over another Tenant’s Instance, VPC, VPC Prefix, or security policy.

Results are ordered by created ascending by default, with Interface id ascending as a stable tie-breaker. orderBy supports status, created, and updated in ascending or descending order; Interface id ascending remains the tie-breaker. An empty result is returned as [].

Authentication

AuthorizationBearer
export JWT_BEARER_TOKEN="<jwt-bearer-token>"

# Example org name: "acme-inc
export ORG_NAME=<org-name>

# Use the JWT bearer token in your API request auth header:
curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current

Path parameters

orgstringRequired
Name of the Tenant organization

Query parameters

vpcIdstringOptionalformat: "uuid"
Filter by the selected VPC or the parent VPC of an explicitly selected VPC Prefix
crossTenantbooleanOptional
Filter by whether the Instance and selected VPC or VPC Prefix have different owning Tenants
instanceTenantIdstringOptionalformat: "uuid"
Filter by the Tenant that owns the consuming Instance, within the caller's visibility boundary
vpcTenantIdstringOptionalformat: "uuid"
Filter by the Tenant that owns the selected VPC or VPC Prefix, within the caller's visibility boundary
statusenumOptional
Filter Interfaces by status
Allowed values:
includeRelationenumOptional

Related entity to expand; repeat the parameter to request multiple relations.

Allowed values:
pageNumberintegerOptional1-21474836
Page number for pagination query
pageSizeintegerOptional1-100Defaults to 20
Page size for pagination query
orderByenumOptionalDefaults to CREATED_ASC

Ordering for pagination query; defaults to CREATED_ASC

Response headers

X-PaginationstringOptional
Pagination result in JSON format

Response

Interfaces visible to the current Tenant
instanceTenantIdstring or nullRead-onlyformat: "uuid"

ID of the Tenant that owns the associated Instance when it differs from the selected VPC or VPC Prefix owner; null when the owners match

vpcTenantIdstring or nullRead-onlyformat: "uuid"

ID of the Tenant that owns the selected VPC or VPC Prefix when it differs from the Instance owner; null when the owners match

idstringOptionalformat: "uuid">=1 character
Unique UUID v4 identifier for the Interface
instanceIdstringOptionalformat: "uuid"
ID of the associated Instance
subnetIdstring or nullOptionalformat: "uuid"
ID of the associated Subnet
vpcPrefixIdstring or nullOptionalformat: "uuid"
ID of the VPC Prefix explicitly selected by the caller
vpcIdstringOptionalformat: "uuid"
ID of the VPC from which the Controller selects a prefix
ipFamilieslist of enumsOptional
Address families requested for Controller prefix selection
Allowed values:
isPhysicalbooleanOptional
Indicates whether the network is bound on a physical Interface
devicestring or nullOptional
Name of the device to use
deviceInstanceinteger or nullOptional
Index of the device, used to identify which interface card to attache the Partition to
virtualFunctionIdinteger or nullOptional
Must be specified if isPhysical is false
macAddressstring or nullOptional
MAC address of the Interface
ipAddresseslist of stringsOptional
A list of IPv4 or IPv6 addresses
ipPrefixeslist of stringsOptionalRead-only

Reported IPv4 or IPv6 prefixes in CIDR notation, ordered IPv4 before IPv6. This list is independent of ipAddresses; SLAAC can report an IPv6 prefix without a fixed host address. Match prefixes and addresses by address family, not list position. Empty when no prefixes are available.

requestedIpAddressstring or nullOptional

Explicitly requested IP address for the interface. This is only used with an explicit vpcPrefixId and is not valid with subnetId or VPC-selected interfaces. The least-significant host bit must be 1.

inlineRoutingProfileobject or nullOptional

Inline interface-local routing profile options. Only valid for VPC-backed interfaces.

statusenumOptional
Status of the Interface
Allowed values:
createddatetimeOptionalRead-only

Date/time when the Interface was created

updateddatetimeOptionalRead-only

Date/time when the Interface was last updated

Errors

400
Bad Request Error
403
Forbidden Error
500
Internal Server Error