Networking

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

List security groups

GET
/scopes/{scopeId}/network/security-groups

Returns the security groups of the active tenant/subscription/project scope as a paginated collection. This single endpoint backs both the plain Security groups page load and every search/filter/sort/pagination control of that view: q performs a case-insensitive substring match against the group name and description, sort accepts the sortable columns name and created (createdAt) with order asc|desc, and page/pageSize window the result. Each row carries the full embedded rules array so the view can render inbound/outbound rule counts, plus attachedPorts for the "Attached ports" counter tiles. Soft-deleted groups (deleted_at set) are never returned. Validation: scopeId must reference a scope the caller can read → 403 otherwise; sort must be one of name|created → 422 VALIDATION_FAILED; page >= 1 and pageSize within the allowed window → 422; unknown region value → 422. Async & state: Synchronous read; no state change. Subsequent resource.updated SSE frames for security-group resources are merged into this cached list by the UI. Errors: 401 when unauthenticated; 403 when the caller has no role on the scope; 422 on malformed query parameters; 500 on read-model failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50

Response Body

Paginated security-group collection for the active scope.

application/json
  1. response
data*array<>
meta*

Pagination envelope metadata. List responses are always { data, meta } — never a naked array.

curl -X GET "https://example.com/scopes/string/network/security-groups"
{  "data": [    {      "origin": "portal",      "id": "string",      "name": "string",      "description": "string",      "rules": [        {          "id": "string",          "direction": "ingress",          "etherType": "IPv4",          "protocol": "tcp",          "portMin": 0,          "portMax": 0,          "remoteCidr": "string",          "remoteGroup": "string",          "description": "string"        }      ],      "attachedPorts": 0,      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}