Skip to content
Download

Gateway

CompozyOS Gateway HTTP endpoints.

For people running agent work32 pages in this section

Audit the current gateway security posture

GET
/api/gateway/audit

Response Body

Completed gateway security audit

application/json
  1. response
auth*
device_highlights*
findings*array<>
local_only*boolean
no_findings*boolean
ran*boolean
status*
Example Request
curl -X GET 'https://example.com/api/gateway/audit'
Example Response
{  "auth": {    "active_device_count": 0,    "mode": "string",    "required_remotely": true  },  "device_highlights": {    "active": 0,    "recently_paired": 0,    "revoked": 0,    "stale": 0,    "stale_device_ids": [      "string"    ]  },  "findings": [    {      "id": "string",      "remediation": "string",      "resource": "string",      "severity": "string",      "summary": "string",      "tier": "string"    }  ],  "local_only": true,  "no_findings": true,  "ran": true,  "status": {    "addresses": [      {        "address": "string",        "live": true,        "tier": "string"      }    ],    "bindings": [      {        "confirmed_at": "2019-08-24T14:15:22Z",        "confirmed_endpoint_generation": 0,        "enable_path": "string",        "endpoint_generation": 0,        "reachability": "string",        "scope_kind": "string",        "subject_id": "string",        "subject_kind": "string",        "url": "string",        "workspace_id": "string"      }    ],    "changed": true,    "devices": [      {        "actor_kind": "string",        "created_at": "2019-08-24T14:15:22Z",        "id": "string",        "last_seen_at": "2019-08-24T14:15:22Z",        "name": "string",        "pairing_origin": "string",        "revoke_epoch": 0,        "revoked_at": "2019-08-24T14:15:22Z"      }    ],    "enabled": true,    "providers": [      {        "cause": "string",        "desired": "string",        "generation": 0,        "health": "string",        "name": "string",        "observed": "string",        "tier": "string"      }    ],    "refusal": {      "cause": "string",      "fix": "string"    },    "surfaces": [      {        "desired": "string",        "generation": 0,        "observed": "string",        "surface": "string",        "tier": "string"      }    ],    "tiers": [      {        "advertised": true,        "desired": "string",        "listener_address": "string",        "observed": "string",        "tier": "string"      }    ]  }}

List the operator-global paired device inventory

GET
/api/gateway/devices

Response Body

OK

application/json
  1. response
devices*array<>
Example Request
curl -X GET 'https://example.com/api/gateway/devices'
Example Response
{  "devices": [    {      "actor_kind": "string",      "created_at": "2019-08-24T14:15:22Z",      "id": "string",      "last_seen_at": "2019-08-24T14:15:22Z",      "name": "string",      "pairing_origin": "string",      "revoke_epoch": 0,      "revoked_at": "2019-08-24T14:15:22Z"    }  ]}

Rename one paired gateway device

PATCH
/api/gateway/devices/{id}

Path Parameters

id*string

Gateway device id

Request Body

JSON request body

application/json
  1. body
name*string

Response Body

Renamed

application/json
  1. response
actor_kind*string
created_at*string
Formatdate-time
id*string
last_seen_at?|
Formatdate-time
name*string
pairing_origin*string
revoke_epoch*integer
Formatuint64
Range0 <= value
revoked_at?|
Formatdate-time
Example Request
curl -X PATCH 'https://example.com/api/gateway/devices/string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
{  "actor_kind": "string",  "created_at": "2019-08-24T14:15:22Z",  "id": "string",  "last_seen_at": "2019-08-24T14:15:22Z",  "name": "string",  "pairing_origin": "string",  "revoke_epoch": 0,  "revoked_at": "2019-08-24T14:15:22Z"}

Revoke one paired gateway device and its live streams

DELETE
/api/gateway/devices/{id}

Path Parameters

id*string

Gateway device id

Response Body

Revoked

application/json
  1. response
canceled*integer
changed*boolean
device*
Example Request
curl -X DELETE 'https://example.com/api/gateway/devices/string'
Example Response
{  "canceled": 0,  "changed": true,  "device": {    "actor_kind": "string",    "created_at": "2019-08-24T14:15:22Z",    "id": "string",    "last_seen_at": "2019-08-24T14:15:22Z",    "name": "string",    "pairing_origin": "string",    "revoke_epoch": 0,    "revoked_at": "2019-08-24T14:15:22Z"  }}

Confirm one subject against the verified public endpoint

POST
/api/gateway/ingress-bindings

Request Body

JSON request body

application/json
  1. body
confirmed*boolean
subject_id*string
subject_kind*string

Response Body

Already confirmed

application/json
  1. response
binding*
changed*boolean
Example Request
curl -X POST 'https://example.com/api/gateway/ingress-bindings' \  -H 'Content-Type: application/json' \  -d '{  "confirmed": true,  "subject_id": "string",  "subject_kind": "string"}'
Example Response
{  "binding": {    "confirmed_at": "2019-08-24T14:15:22Z",    "confirmed_endpoint_generation": 0,    "enable_path": "string",    "endpoint_generation": 0,    "reachability": "string",    "scope_kind": "string",    "subject_id": "string",    "subject_kind": "string",    "url": "string",    "workspace_id": "string"  },  "changed": true}

Remove one public ingress confirmation

DELETE
/api/gateway/ingress-bindings/{subject_kind}/{subject_id}

Path Parameters

subject_kind*string

Ingress subject kind

subject_id*string

Ingress subject id

Response Body

Unbound

application/json
  1. response
changed*boolean
subject_id*string
subject_kind*string
Example Request
curl -X DELETE 'https://example.com/api/gateway/ingress-bindings/string/string'
Example Response
{  "changed": true,  "subject_id": "string",  "subject_kind": "string"}

Mint a bounded one-time gateway pairing artifact

POST
/api/gateway/pairings

Response Body

Created

application/json
  1. response
artifact*string
expires_at*string
Formatdate-time
Example Request
curl -X POST 'https://example.com/api/gateway/pairings'
Example Response
{  "artifact": "string",  "expires_at": "2019-08-24T14:15:22Z"}

Redeem a one-time gateway pairing artifact

POST
/api/gateway/pairings/redeem

Request Body

JSON request body

application/json
  1. body
actor_kind*string
artifact*string
credential?string
name*string

Response Body

Redeemed

application/json
  1. response
credential?string
device*
Example Request
curl -X POST 'https://example.com/api/gateway/pairings/redeem' \  -H 'Content-Type: application/json' \  -d '{  "actor_kind": "string",  "artifact": "string",  "name": "string"}'
Example Response
{  "credential": "string",  "device": {    "actor_kind": "string",    "created_at": "2019-08-24T14:15:22Z",    "id": "string",    "last_seen_at": "2019-08-24T14:15:22Z",    "name": "string",    "pairing_origin": "string",    "revoke_epoch": 0,    "revoked_at": "2019-08-24T14:15:22Z"  }}

Disable one named connectivity provider for a gateway tier

POST
/api/gateway/providers/{name}/disable

Path Parameters

name*string

Connectivity provider name

Query Parameters

tier*string

Gateway tier

Response Body

Disabled

application/json
  1. response
addresses*array<>
bindings*array<>
changed*boolean
devices*array<>
enabled*boolean
providers*array<>
refusal?|
surfaces*array<>
tiers*array<>
Example Request
curl -X POST 'https://example.com/api/gateway/providers/string/disable?tier=string'
Example Response
{  "addresses": [    {      "address": "string",      "live": true,      "tier": "string"    }  ],  "bindings": [    {      "confirmed_at": "2019-08-24T14:15:22Z",      "confirmed_endpoint_generation": 0,      "enable_path": "string",      "endpoint_generation": 0,      "reachability": "string",      "scope_kind": "string",      "subject_id": "string",      "subject_kind": "string",      "url": "string",      "workspace_id": "string"    }  ],  "changed": true,  "devices": [    {      "actor_kind": "string",      "created_at": "2019-08-24T14:15:22Z",      "id": "string",      "last_seen_at": "2019-08-24T14:15:22Z",      "name": "string",      "pairing_origin": "string",      "revoke_epoch": 0,      "revoked_at": "2019-08-24T14:15:22Z"    }  ],  "enabled": true,  "providers": [    {      "cause": "string",      "desired": "string",      "generation": 0,      "health": "string",      "name": "string",      "observed": "string",      "tier": "string"    }  ],  "refusal": {    "cause": "string",    "fix": "string"  },  "surfaces": [    {      "desired": "string",      "generation": 0,      "observed": "string",      "surface": "string",      "tier": "string"    }  ],  "tiers": [    {      "advertised": true,      "desired": "string",      "listener_address": "string",      "observed": "string",      "tier": "string"    }  ]}

Enable one connectivity provider for a gateway tier

POST
/api/gateway/providers/{name}/enable

Path Parameters

name*string

Connectivity provider name

Request Body

JSON request body

application/json
  1. body
digest_confirmed?string
expected_generation*integer
Formatuint64
Range0 <= value
install_source*string
tier*string

Response Body

Enabled

application/json
  1. response
addresses*array<>
bindings*array<>
changed*boolean
devices*array<>
enabled*boolean
providers*array<>
refusal?|
surfaces*array<>
tiers*array<>
Example Request
curl -X POST 'https://example.com/api/gateway/providers/string/enable' \  -H 'Content-Type: application/json' \  -d '{  "expected_generation": 0,  "install_source": "string",  "tier": "string"}'
Example Response
{  "addresses": [    {      "address": "string",      "live": true,      "tier": "string"    }  ],  "bindings": [    {      "confirmed_at": "2019-08-24T14:15:22Z",      "confirmed_endpoint_generation": 0,      "enable_path": "string",      "endpoint_generation": 0,      "reachability": "string",      "scope_kind": "string",      "subject_id": "string",      "subject_kind": "string",      "url": "string",      "workspace_id": "string"    }  ],  "changed": true,  "devices": [    {      "actor_kind": "string",      "created_at": "2019-08-24T14:15:22Z",      "id": "string",      "last_seen_at": "2019-08-24T14:15:22Z",      "name": "string",      "pairing_origin": "string",      "revoke_epoch": 0,      "revoked_at": "2019-08-24T14:15:22Z"    }  ],  "enabled": true,  "providers": [    {      "cause": "string",      "desired": "string",      "generation": 0,      "health": "string",      "name": "string",      "observed": "string",      "tier": "string"    }  ],  "refusal": {    "cause": "string",    "fix": "string"  },  "surfaces": [    {      "desired": "string",      "generation": 0,      "observed": "string",      "surface": "string",      "tier": "string"    }  ],  "tiers": [    {      "advertised": true,      "desired": "string",      "listener_address": "string",      "observed": "string",      "tier": "string"    }  ]}

Get the operator-global gateway posture

GET
/api/gateway/status

Response Body

OK

application/json
  1. response
addresses*array<>
bindings*array<>
changed*boolean
devices*array<>
enabled*boolean
providers*array<>
refusal?|
surfaces*array<>
tiers*array<>
Example Request
curl -X GET 'https://example.com/api/gateway/status'
Example Response
{  "addresses": [    {      "address": "string",      "live": true,      "tier": "string"    }  ],  "bindings": [    {      "confirmed_at": "2019-08-24T14:15:22Z",      "confirmed_endpoint_generation": 0,      "enable_path": "string",      "endpoint_generation": 0,      "reachability": "string",      "scope_kind": "string",      "subject_id": "string",      "subject_kind": "string",      "url": "string",      "workspace_id": "string"    }  ],  "changed": true,  "devices": [    {      "actor_kind": "string",      "created_at": "2019-08-24T14:15:22Z",      "id": "string",      "last_seen_at": "2019-08-24T14:15:22Z",      "name": "string",      "pairing_origin": "string",      "revoke_epoch": 0,      "revoked_at": "2019-08-24T14:15:22Z"    }  ],  "enabled": true,  "providers": [    {      "cause": "string",      "desired": "string",      "generation": 0,      "health": "string",      "name": "string",      "observed": "string",      "tier": "string"    }  ],  "refusal": {    "cause": "string",    "fix": "string"  },  "surfaces": [    {      "desired": "string",      "generation": 0,      "observed": "string",      "surface": "string",      "tier": "string"    }  ],  "tiers": [    {      "advertised": true,      "desired": "string",      "listener_address": "string",      "observed": "string",      "tier": "string"    }  ]}

Mint a short-lived single-use stream ticket

POST
/api/gateway/stream-tickets

Response Body

Created

application/json
  1. response
expires_at*string
Formatdate-time
ticket*string
Example Request
curl -X POST 'https://example.com/api/gateway/stream-tickets'
Example Response
{  "expires_at": "2019-08-24T14:15:22Z",  "ticket": "string"}

Set durable exposure for one gateway surface

POST
/api/gateway/surfaces

Request Body

JSON request body

application/json
  1. body
consent*boolean
desired*string
expected_generation*integer
Formatuint64
Range0 <= value
surface*string
tier*string

Response Body

Updated

application/json
  1. response
addresses*array<>
bindings*array<>
changed*boolean
devices*array<>
enabled*boolean
providers*array<>
refusal?|
surfaces*array<>
tiers*array<>
Example Request
curl -X POST 'https://example.com/api/gateway/surfaces' \  -H 'Content-Type: application/json' \  -d '{  "consent": true,  "desired": "string",  "expected_generation": 0,  "surface": "string",  "tier": "string"}'
Example Response
{  "addresses": [    {      "address": "string",      "live": true,      "tier": "string"    }  ],  "bindings": [    {      "confirmed_at": "2019-08-24T14:15:22Z",      "confirmed_endpoint_generation": 0,      "enable_path": "string",      "endpoint_generation": 0,      "reachability": "string",      "scope_kind": "string",      "subject_id": "string",      "subject_kind": "string",      "url": "string",      "workspace_id": "string"    }  ],  "changed": true,  "devices": [    {      "actor_kind": "string",      "created_at": "2019-08-24T14:15:22Z",      "id": "string",      "last_seen_at": "2019-08-24T14:15:22Z",      "name": "string",      "pairing_origin": "string",      "revoke_epoch": 0,      "revoked_at": "2019-08-24T14:15:22Z"    }  ],  "enabled": true,  "providers": [    {      "cause": "string",      "desired": "string",      "generation": 0,      "health": "string",      "name": "string",      "observed": "string",      "tier": "string"    }  ],  "refusal": {    "cause": "string",    "fix": "string"  },  "surfaces": [    {      "desired": "string",      "generation": 0,      "observed": "string",      "surface": "string",      "tier": "string"    }  ],  "tiers": [    {      "advertised": true,      "desired": "string",      "listener_address": "string",      "observed": "string",      "tier": "string"    }  ]}

Extensions

CompozyOS Extensions HTTP endpoints.

App tokens

CompozyOS App tokens HTTP endpoints.