This reference is currently available in English. The Cloud console remains in your selected language.

BEEOS CLOUD / DEVELOPER REFERENCE

Device bindings

Agent bind sessions and portal bind sessions.

Overview

The device bindings domain covers the bind sessions that connect an agent to a user: agent bind sessions, and portal bind sessions that a portal creates, reads, revokes, and resolves.

6 operations · SDK resource: TypeScript cloud.deviceBindings · Python cloud.device_bindings · Go cloud.DeviceBindings · API overview

Main objects

agentBindDetailsWire and agentBindWire: the details and the result of an agent bind session.
portalBindWire: a portal bind session.
Binding: the binding that results.

agentBindDetailsWire

Field	Type	Required	Description
`bind_id`	`string`	yes	ID of the bind session.
`hostname`	`string`	yes	Host name the device reported.
`fingerprint_short`	`string`	yes	First 16 characters of the device key fingerprint. Show it to the user to compare with the device.
`harness`	`string`	yes	Harness the device runs, as the device reported it.
`os_type`	`string`	no	Operating system the device reported. Omitted when it did not report one.
`expires_at`	`integer`	yes	Time the session expires, in Unix seconds.
`status`	`string`	yes	State of the bind session. A session that has expired is deleted, so lookups of an expired session fail with 404 `not_found` instead. Allowed values: `"pending"` — Created by the device and waiting for a user to confirm it; `"confirming"` — A user confirmed it and the instance for the device is being created; `"bound"` — Confirmed: the instance exists and the device can connect to it. (enum table)
`server_time`	`integer`	yes	Current server time in Unix seconds. Compare it with `expires_at` to get the remaining time without clock skew.

Every field, and the methods that use this object: appendix.

agentBindWire

Field	Type	Required	Description
`status`	`string`	yes	State of the bind session. After a successful confirmation it is `bound`; a session that is still waiting for confirmation reports `pending`. Allowed values: `"pending"` — Created by the device and waiting for a user to confirm it. A session that is being confirmed also reports `pending`; `"bound"` — Confirmed: the instance exists and the device can connect to it. (enum table)
`bind_id`	`string`	no	ID of the bind session.
`instance_id`	`string`	no	ID of the instance created for the device. Present once the session is bound.
`public_key`	`string`	no	Public key the device registered for the session.
`hostname`	`string`	no	Host name the device reported.
`expires_at`	`integer`	no	Time the session expires, in Unix seconds.
`runtime_binding`	bindRuntimeWire	no	Addresses a bound self-hosted agent connects to. Present once the session is bound. Nullable.

Every field, and the methods that use this object: appendix.

portalBindWire

Field	Type	Required	Description
`provider_id`	`string`	no	ID of the provider that hosts the instance. Set when a new instance was created for the device.
`bind_id`	`string`	yes	ID of the bind session. It starts with `portal_`.
`short_code`	`string`	yes	Short code the user can enter on the device instead of scanning the QR code. It uses uppercase letters and digits without look-alike characters.
`status`	`string`	yes	State of the portal bind session. A session that has expired is deleted, so lookups of an expired session fail with 404 `not_found` instead. Allowed values: see the table below, portalBindWire.status values.
`instance_id`	`string`	no	ID of the instance bound to the device. Present once the session is bound.
`expires_at`	`integer`	yes	Time the session expires, in Unix seconds. A session is valid for 10 minutes.
`name`	`string`	yes	Display name for the instance created for the device. Defaults to `BeeRunner`.
`qr_payload`	`string`	no	Link to encode in the QR code the device scans. Returned only when the session is created.
`api_base_url`	`string`	no	Base URL of the API the device connects to. Returned only when the session is created.
`relay_url`	`string`	no	URL of the relay the device connects through. Returned only when the session is created.
`desired_status`	`string`	no	Lifecycle phase the created instance is driven toward: `running`. Set when a new instance was created for the device.
`connectivity`	`string`	no	Reachability of the created instance: `unknown`, `online` or `offline`. Set when a new instance was created for the device.
`resource_version`	`integer`	no	Resource version of the created instance. Set when a new instance was created for the device.

portalBindWire.status values

Value	Meaning
`"pending"`	Created and waiting for a device to scan the QR code or enter the short code.
`"awaiting_confirmation"`	A device claimed the session. Call the resolve operation with `decision` to continue.
`"confirming"`	The decision `create` was accepted and a new instance is being created for the device.
`"bound"`	The device is bound to an instance, given by `instance_id`.
`"revoked"`	Revoked with the revoke operation. A revoked session cannot be claimed or resolved.

Every field, and the methods that use this object: appendix.

Binding

Field	Type	Required	Description
`client_type`	`string`	yes	How the token is bound to the client. Allowed values: `"web"` — Bound to a web page origin, returned in `origin`; `"native"` — Bound to a device key, whose thumbprint is returned in `cnf_jkt`. (enum table) Structure by `client_type`: see the variant table.
`origin`	`string`	no	Origin the token is bound to. Returned when `client_type` is `web`. Constraints: `format=uri`.
`cnf_jkt`	`string`	no	Thumbprint of the device key the token is bound to. Returned when `client_type` is `native`.

Every field, and the methods that use this object: appendix.

Typical flow

For an agent bind session, read its details with deviceBindings.getDetails, then accept it with deviceBindings.confirm.
For a portal, create a bind session with deviceBindings.createPortal and read it with deviceBindings.getPortal.
End it with deviceBindings.resolvePortal (the decision is recover or create) or deviceBindings.revokePortal.

Methods

Method	HTTP	Summary
deviceBindings.confirm	`POST /v1/agent/bind/{id}/confirm`	Confirm an agent bind session
deviceBindings.getDetails	`GET /v1/agent/bind/{id}/details`	Get agent bind session details
deviceBindings.createPortal	`POST /v1/agent/portal/bind-sessions`	Create a portal bind session
deviceBindings.getPortal	`GET /v1/agent/portal/bind-sessions/{id}`	Get a portal bind session
deviceBindings.resolvePortal	`POST /v1/agent/portal/bind-sessions/{id}/resolve`	Resolve a portal bind session
deviceBindings.revokePortal	`POST /v1/agent/portal/bind-sessions/{id}/revoke`	Revoke a portal bind session

deviceBindings.confirm

POST /v1/agent/bind/{id}/confirm · Operation ID confirmAgentBind

Confirm an agent bind session

SDK methods

Language	Method	Signature
TypeScript	`cloud.deviceBindings.confirm`	`confirm(id: string, input: Models.ConfirmAgentBindRequest): Promise<Models.ConfirmAgentBindResponse>`
Python	`cloud.device_bindings.confirm`	`def confirm(self, id: str, input: ConfirmAgentBindRequest) -> ConfirmAgentBindResponse`
Go	`cloud.DeviceBindings.Confirm`	`func (r *DeviceBindingsResource) Confirm(ctx context.Context, id string, input ConfirmAgentBindRequest) (ConfirmAgentBindResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`id`	path	`string`	yes	ID of the agent bind session to confirm, the `bind_id` returned when the device created it.

Request body

application/json · required

Field	Type	Required	Description
`name`	`string`	no	Display name for the instance created for the device, up to 128 characters. Defaults to the host name the device reported.
`modelPrimary`	`string`	no	Accepted and ignored. The instance keeps the default model of the server.
`model_primary`	`string`	no	Snake-case alias of `modelPrimary`, also ignored. If both are sent they must be equal.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	agentBindWire	yes	—

Errors

Status	Schema	Description
other (default)	DeviceBindingErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.confirm("id_123", {});
console.log(result);

deviceBindings.getDetails

GET /v1/agent/bind/{id}/details · Operation ID getAgentBindDetails

Get agent bind session details

SDK methods

Language	Method	Signature
TypeScript	`cloud.deviceBindings.getDetails`	`getDetails(id: string): Promise<Models.GetAgentBindDetailsResponse>`
Python	`cloud.device_bindings.get_details`	`def get_details(self, id: str) -> GetAgentBindDetailsResponse`
Go	`cloud.DeviceBindings.GetDetails`	`func (r *DeviceBindingsResource) GetDetails(ctx context.Context, id string) (GetAgentBindDetailsResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`id`	path	`string`	yes	ID of the agent bind session, the `bind_id` returned when the device created it.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	agentBindDetailsWire	yes	—

Errors

Status	Schema	Description
other (default)	DeviceBindingErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.getDetails("id_123");
console.log(result);

deviceBindings.createPortal

POST /v1/agent/portal/bind-sessions · Operation ID createPortalBind

Create a portal bind session

SDK methods

Language	Method	Signature
TypeScript	`cloud.deviceBindings.createPortal`	`createPortal(input: Models.CreatePortalBindRequest): Promise<Models.CreatePortalBindResponse>`
Python	`cloud.device_bindings.create_portal`	`def create_portal(self, input: CreatePortalBindRequest) -> CreatePortalBindResponse`
Go	`cloud.DeviceBindings.CreatePortal`	`func (r *DeviceBindingsResource) CreatePortal(ctx context.Context, input CreatePortalBindRequest) (CreatePortalBindResponse, error)`

Request body

application/json · required

Field	Type	Required	Description
`name`	`string`	no	Display name for the instance created for the device, up to 128 characters. Defaults to `BeeRunner`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	portalBindWire	yes	—

Errors

Status	Schema	Description
other (default)	DeviceBindingErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.createPortal({});
console.log(result);

deviceBindings.getPortal

GET /v1/agent/portal/bind-sessions/{id} · Operation ID getPortalBind

Get a portal bind session

SDK methods

Language	Method	Signature
TypeScript	`cloud.deviceBindings.getPortal`	`getPortal(id: string): Promise<Models.GetPortalBindResponse>`
Python	`cloud.device_bindings.get_portal`	`def get_portal(self, id: str) -> GetPortalBindResponse`
Go	`cloud.DeviceBindings.GetPortal`	`func (r *DeviceBindingsResource) GetPortal(ctx context.Context, id string) (GetPortalBindResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`id`	path	`string`	yes	ID of the portal bind session, the `bind_id` returned when it was created. It starts with `portal_`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	portalBindWire	yes	—

Errors

Status	Schema	Description
other (default)	DeviceBindingErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.getPortal("id_123");
console.log(result);

deviceBindings.resolvePortal

POST /v1/agent/portal/bind-sessions/{id}/resolve · Operation ID resolvePortalBind

Resolve a portal bind session

SDK methods

Language	Method	Signature
TypeScript	`cloud.deviceBindings.resolvePortal`	`resolvePortal(id: string, input: Models.ResolvePortalBindRequest): Promise<Models.ResolvePortalBindResponse>`
Python	`cloud.device_bindings.resolve_portal`	`def resolve_portal(self, id: str, input: ResolvePortalBindRequest) -> ResolvePortalBindResponse`
Go	`cloud.DeviceBindings.ResolvePortal`	`func (r *DeviceBindingsResource) ResolvePortal(ctx context.Context, id string, input ResolvePortalBindRequest) (ResolvePortalBindResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`id`	path	`string`	yes	ID of the portal bind session, the `bind_id` returned when it was created. It starts with `portal_`.

Request body

application/json · required

Field	Type	Required	Description
`decision`	`string`	yes	What to do with the device that claimed the session. Required. Allowed values: `"recover"` — Bind the device to the existing instance given by `instance_id`; `"create"` — Create a new instance for the device. (enum table)
`instance_id`	`string`	no	ID of the existing instance to bind the device to. Required when `decision` is `recover`; ignored for `create`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	portalBindWire	yes	—

Errors

Status	Schema	Description
other (default)	DeviceBindingErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.resolvePortal("id_123", { decision: "recover" });
console.log(result);

deviceBindings.revokePortal

POST /v1/agent/portal/bind-sessions/{id}/revoke · Operation ID revokePortalBind

Revoke a portal bind session

SDK methods

Language	Method	Signature
TypeScript	`cloud.deviceBindings.revokePortal`	`revokePortal(id: string): Promise<Models.RevokePortalBindResponse>`
Python	`cloud.device_bindings.revoke_portal`	`def revoke_portal(self, id: str) -> RevokePortalBindResponse`
Go	`cloud.DeviceBindings.RevokePortal`	`func (r *DeviceBindingsResource) RevokePortal(ctx context.Context, id string) (RevokePortalBindResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`id`	path	`string`	yes	ID of the portal bind session, the `bind_id` returned when it was created. It starts with `portal_`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	portalBindWire	yes	—

Errors

Status	Schema	Description
other (default)	DeviceBindingErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.deviceBindings.revokePortal("id_123");
console.log(result);

Structures by discriminator

Binding by client_type

The structure of Binding depends on its own client_type value.

Value of client_type	Description	Structure
`"web"`	Bound to a web page origin, returned in `origin`.	BindingWeb
`"native"`	Bound to a device key, whose thumbprint is returned in `cnf_jkt`.	BindingNative

BeeOS CloudBack to documentation