Skip to main content

PairingExchangeResponse

One-time credential response returned after successful pairing.

deviceIdstring<uuid>required

Stable identifier assigned to the device.

cluster objectrequired

Validated cluster identity bound to the credential.

formatVersionFormatversion (integer)

Cluster identity format version.

Constant value: 1
Default value: 1
clusterIdstring<uuid4>required

Stable random cluster ID used in pairing and compatibility checks.

nameName (string)

Operator-visible cluster name; defaults to Cluster.

Possible values: non-empty and <= 80 characters

Default value: Cluster
publicKeyPublickey (string)required

Unpadded URL-safe base64 Ed25519 cluster public key.

fingerprintFingerprint (string)required

SHA-256 fingerprint derived from the cluster public key.

createdAtstring<date-time>required

Timezone-aware UTC timestamp when the cluster identity was created.

accessTokenAccesstoken (string)required

Opaque short-lived bearer credential returned only once.

accessTokenExpiresAtstring<date-time>required

UTC expiry of the access credential.

refreshTokenRefreshtoken (string)required

Opaque rotating refresh credential returned only once.

refreshTokenExpiresAtstring<date-time>required

UTC expiry of the refresh credential.

scopesOperatorScope (string)[]required

Canonical API scopes granted to the paired device.

Possible values: [cluster:read, models:read, chat:write, operations:write, devices:manage, plugins:read, plugins:manage, plugins:approve]

remoteAccess object

One-time relay and pinned inner-TLS material when this gateway has remote access configured.

anyOf
transportTransport (string)required

Selected remote carrier contract.

Constant value: paired_websocket_v1
appWebsocketUrlAppwebsocketurl (string)required

Outer WebSocket endpoint used for each independent request.

routingLocatorRoutinglocator (string)required

Opaque relay route locator.

appCarrierCredentialAppcarriercredential (string)required

Opaque app-role carrier bearer stored in platform secure storage.

gatewayServerNameGatewayservername (string)required

Inner TLS server name authenticated by the pinned certificate.

gatewayCaCertificatePemGatewaycacertificatepem (string)required

PEM trust anchor for end-to-end TLS terminating at Skulk.

PairingExchangeResponse
{
  "deviceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cluster": {
    "formatVersion": 1,
    "clusterId": "string",
    "name": "Cluster",
    "publicKey": "string",
    "fingerprint": "string",
    "createdAt": "2024-07-29T15:51:28.071Z"
  },
  "accessToken": "string",
  "accessTokenExpiresAt": "2024-07-29T15:51:28.071Z",
  "refreshToken": "string",
  "refreshTokenExpiresAt": "2024-07-29T15:51:28.071Z",
  "scopes": [
    "cluster:read"
  ],
  "remoteAccess": {
    "transport": "paired_websocket_v1",
    "appWebsocketUrl": "string",
    "routingLocator": "string",
    "appCarrierCredential": "string",
    "gatewayServerName": "string",
    "gatewayCaCertificatePem": "string"
  }
}