EN

BEEOS CLOUD / DEVELOPER REFERENCE

Identity

Client sessions for browser and mobile clients, and external-user data deletion.

Overview

The identity domain manages the product users your backend acts for. It issues, refreshes, and revokes client sessions (short-lived client tokens for a web or native client) and starts and tracks the deletion of an external user's data. Every operation here takes an Idempotency-Key, except the read of a deletion.

5 operations · SDK resource: TypeScript cloud.identity · Python cloud.identity · Go cloud.Identity · API overview

Main objects

ClientSessionInput: the request for a client session (client type, requested capabilities, optional ttl_seconds).
ClientSessionResponse: the issued client token with its session ID, client API URL, and expiry.
DeletionAccepted and Deletion: the receipt and the state of an external user's data deletion.
ExternalUserID: the opaque, app-local ID of a product user.

ClientSessionInput

Field	Type	Required	Description
`client_type`	`string`	yes	How the client token is bound to the client that will use it. It decides whether you send `origin` or `device_attestation`. Allowed values: `"web"` — A browser client. The token is bound to the page origin you send in `origin`, which must be one of the allowed origins configured for the app. `device_attestation` must not be sent. A request that does not match this binding returns 403 `invalid_origin`; `"native"` — A native app. The token is bound to a device key whose thumbprint you send in `device_attestation.jkt`. `origin` must not be sent. A request that does not match this binding returns 403 `invalid_origin`. (enum table) Structure by `client_type`: see the variant table.
`requested_capabilities`	`array<string>`	yes	Operations the client token may perform on the Client API, 1 or more distinct names. Each name must be one of `context:read`, `instances:read`, `instances:write`, `agents:read`, `agents:invoke`, `files:read`, `files:write`, `files:delete`, `events:read`, `viewer:connect` and `terminal:connect`, and must be allowed for your app's clients. Any other name returns 403 `invalid_capability`. Constraints: `minItems=1`, `uniqueItems`.
`origin`	`string`	no	Origin of the web page that will use the token, for example `https://app.example.com`. Required when `client_type` is `web`, and it must exactly match one of the allowed origins configured for the app; otherwise the request returns 403 `invalid_origin`. Not allowed when `client_type` is `native`, which also returns 403 `invalid_origin`. Constraints: `format=uri`.
`device_attestation`	`object`	no	Proof of the device key the token is bound to. Required when `client_type` is `native`; not allowed when `client_type` is `web`, which returns 403 `invalid_origin`.
`device_attestation.jkt`	`string`	yes	Thumbprint of the device's public key, the base64url-encoded SHA-256 JWK thumbprint, at least 16 characters. Later Client API requests must be signed with the matching private key. Constraints: `minLength=16`.
`ttl_seconds`	`integer`	no	Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request. Default: `600`. Constraints: `minimum=60`, `maximum=1800`.

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

ClientSessionResponse

Field	Type	Required	Description
`access_token`	`string`	yes	Client token to send as the bearer credential to the Client API. It is shown only in this response, so store it securely on the client and never log it. Write-only.
`client_api_url`	`string`	yes	Base URL of the Client API that accepts `access_token`. Allowed values: `"https://client-api.cloud.beeos.ai/v1"` — The production Client API.
`expires_at`	`string`	yes	Actual expiration of the issued token, capped by the remaining session authorization lifetime. Constraints: `format=date-time`.
`session_id`	`string`	yes	ID of the client session. Use it to refresh or revoke the session. Refreshing issues a new token for the same session.
`app_id`	`string`	yes	ID of the app the session belongs to.
`external_user_id`	`string`	yes	Unused. Cloud does not accept an external user id. Stored sessions leave this empty.
`capabilities`	`array<string>`	yes	Operations the token may perform on the Client API. They are the requested capabilities, without duplicates.
`binding`	Binding	yes	How the token is bound to the client, as requested when the session was created.

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

DeletionAccepted

Field	Type	Required	Description
`deletion_id`	`string`	yes	ID of the deletion. Use it to read the progress of the deletion.
`status`	`string`	yes	State of the deletion when the request was accepted. Allowed values: `"pending"` — The deletion is queued and has not started; `"processing"` — The deletion is running; `"failed"` — The latest attempt stopped with an error, shown in `error_code`. The deletion is retried automatically; `"completed"` — All data of the user was deleted. (enum table)

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

Deletion

Field	Type	Required	Description
`id`	`string`	yes	ID of the deletion.
`status`	`string`	yes	State of the deletion. Poll until it is `completed`. Allowed values: `"pending"` — The deletion is queued and has not started; `"processing"` — The deletion is running; `"failed"` — The latest attempt stopped with an error, shown in `error_code`. The deletion is retried automatically; `"completed"` — All data of the user was deleted. (enum table)
`deleted_resources`	`map<string, integer>`	yes	Number of items deleted so far, as an object that maps a kind of data to a count. The counts are final when `status` is `completed`. Kinds can be added, so do not depend on a fixed set of keys.

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

Create a session for a signed-in product user with identity.createClientSession and hand the token to the client.
Before the token expires, rotate it with identity.refreshClientSession.
End the session with identity.revokeClientSession.
To erase a user's data, call identity.deleteExternalUser; it returns DeletionAccepted. Read the outcome with identity.getExternalUserDeletion.

Methods

Method	HTTP	Summary
identity.createClientSession	`POST /v1/client-sessions`	Create a client session
identity.revokeClientSession	`DELETE /v1/client-sessions/{sessionId}`	Revoke a client session
identity.refreshClientSession	`POST /v1/client-sessions/{sessionId}/refresh`	Refresh a client session
identity.deleteExternalUser	`DELETE /v1/external-users/{externalUserId}`	Start external user data deletion
identity.getExternalUserDeletion	`GET /v1/external-users/{externalUserId}/deletions/{deletionId}`	Get an external user data deletion

identity.createClientSession

POST /v1/client-sessions · Operation ID createClientSession

Create a client session

Issue a client token with request-scoped ttl_seconds. The omitted value normalizes to 600 before idempotency comparison; reusing an Idempotency-Key with a different normalized TTL returns 409 idempotency_conflict.

Idempotency-Key is required.

SDK methods

Language	Method	Signature
TypeScript	`cloud.identity.createClientSession`	`createClientSession(input: Models.ClientSessionInput, idempotencyKey: string): Promise<Models.CreateClientSessionResponse>`
Python	`cloud.identity.create_client_session`	`def create_client_session(self, input: ClientSessionInput, options: CreateClientSessionOptions) -> ClientSessionResponse`
Go	`cloud.Identity.CreateClientSession`	`func (r *IdentityResource) CreateClientSession(ctx context.Context, input ClientSessionInput, options CreateClientSessionOptions) (ClientSessionResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=1`, `maxLength=256`.

Request body

application/json · required · Schema: ClientSessionInput

Field	Type	Required	Description
`client_type`	`string`	yes	How the client token is bound to the client that will use it. It decides whether you send `origin` or `device_attestation`. Allowed values: `"web"` — A browser client. The token is bound to the page origin you send in `origin`, which must be one of the allowed origins configured for the app. `device_attestation` must not be sent. A request that does not match this binding returns 403 `invalid_origin`; `"native"` — A native app. The token is bound to a device key whose thumbprint you send in `device_attestation.jkt`. `origin` must not be sent. A request that does not match this binding returns 403 `invalid_origin`. (enum table) Structure by `client_type`: see the variant table.
`requested_capabilities`	`array<string>`	yes	Operations the client token may perform on the Client API, 1 or more distinct names. Each name must be one of `context:read`, `instances:read`, `instances:write`, `agents:read`, `agents:invoke`, `files:read`, `files:write`, `files:delete`, `events:read`, `viewer:connect` and `terminal:connect`, and must be allowed for your app's clients. Any other name returns 403 `invalid_capability`. Constraints: `minItems=1`, `uniqueItems`.
`origin`	`string`	no	Origin of the web page that will use the token, for example `https://app.example.com`. Required when `client_type` is `web`, and it must exactly match one of the allowed origins configured for the app; otherwise the request returns 403 `invalid_origin`. Not allowed when `client_type` is `native`, which also returns 403 `invalid_origin`. Constraints: `format=uri`.
`device_attestation`	`object`	no	Proof of the device key the token is bound to. Required when `client_type` is `native`; not allowed when `client_type` is `web`, which returns 403 `invalid_origin`.
`device_attestation.jkt`	`string`	yes	Thumbprint of the device's public key, the base64url-encoded SHA-256 JWK thumbprint, at least 16 characters. Later Client API requests must be signed with the matching private key. Constraints: `minLength=16`.
`ttl_seconds`	`integer`	no	Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request. Default: `600`. Constraints: `minimum=60`, `maximum=1800`.

Response

200 Short-lived client token · application/json · Schema: ClientSessionResponse

Field	Type	Required	Description
`access_token`	`string`	yes	Client token to send as the bearer credential to the Client API. It is shown only in this response, so store it securely on the client and never log it. Write-only.
`client_api_url`	`string`	yes	Base URL of the Client API that accepts `access_token`. Allowed values: `"https://client-api.cloud.beeos.ai/v1"` — The production Client API.
`expires_at`	`string`	yes	Actual expiration of the issued token, capped by the remaining session authorization lifetime. Constraints: `format=date-time`.
`session_id`	`string`	yes	ID of the client session. Use it to refresh or revoke the session. Refreshing issues a new token for the same session.
`app_id`	`string`	yes	ID of the app the session belongs to.
`external_user_id`	`string`	yes	Unused. Cloud does not accept an external user id. Stored sessions leave this empty.
`capabilities`	`array<string>`	yes	Operations the token may perform on the Client API. They are the requested capabilities, without duplicates.
`binding`	Binding	yes	How the token is bound to the client, as requested when the session was created.

Errors

Status	Schema	Description
other (default)	ErrorResponse	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.identity.createClientSession({
  client_type: "web",
  requested_capabilities: ["example_requested_capabilities"]
}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.revokeClientSession

DELETE /v1/client-sessions/{sessionId} · Operation ID revokeClientSession

Revoke a client session

Idempotency-Key is required.

SDK methods

Language	Method	Signature
TypeScript	`cloud.identity.revokeClientSession`	`revokeClientSession(sessionId: string, idempotencyKey: string): Promise<Models.RevokeClientSessionResponse>`
Python	`cloud.identity.revoke_client_session`	`def revoke_client_session(self, session_id: str, options: RevokeClientSessionOptions) -> None`
Go	`cloud.Identity.RevokeClientSession`	`func (r *IdentityResource) RevokeClientSession(ctx context.Context, sessionId string, options RevokeClientSessionOptions) error`

Parameters

Parameter	In	Type	Required	Description
`sessionId`	path	`string`	yes	ID of the client session, the `session_id` returned when it was created.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=1`, `maxLength=256`.

Response

204 Session revoked or already revoked

No response body.

Errors

Status	Schema	Description
other (default)	ErrorResponse	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.identity.revokeClientSession("session_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.refreshClientSession

POST /v1/client-sessions/{sessionId}/refresh · Operation ID refreshClientSession

Refresh a client session

Rotate the client token with request-scoped ttl_seconds. The omitted value normalizes to 600 before idempotency comparison; reusing an Idempotency-Key with a different normalized TTL returns 409 idempotency_conflict.

Idempotency-Key is required.

SDK methods

Language	Method	Signature
TypeScript	`cloud.identity.refreshClientSession`	`refreshClientSession(sessionId: string, input: Models.RefreshClientSessionRequest, idempotencyKey: string): Promise<Models.RefreshClientSessionResponse>`
Python	`cloud.identity.refresh_client_session`	`def refresh_client_session(self, session_id: str, input: RefreshClientSessionRequest \| None = None, *, options: RefreshClientSessionOptions) -> ClientSessionResponse`
Go	`cloud.Identity.RefreshClientSession`	`func (r IdentityResource) RefreshClientSession(ctx context.Context, sessionId string, input RefreshClientSessionRequest, options RefreshClientSessionOptions) (ClientSessionResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`sessionId`	path	`string`	yes	ID of the client session, the `session_id` returned when it was created.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=1`, `maxLength=256`.

Request body

application/json · optional

Field	Type	Required	Description
`requested_capabilities`	`array<string>`	no	Operations the new token may perform. Each must already be granted to the session; the new set can only be equal or narrower. Omit it to keep the current capabilities. Names are listed on `requested_capabilities` of the create operation. Constraints: `uniqueItems`.
`ttl_seconds`	`integer`	no	Requested token lifetime in seconds for this issuance. Explicit values outside 60..1800 return 400 invalid_request. Default: `600`. Constraints: `minimum=60`, `maximum=1800`.

Response

200 Rotated JTI with equal or narrower capabilities · application/json · Schema: ClientSessionResponse

Field	Type	Required	Description
`access_token`	`string`	yes	Client token to send as the bearer credential to the Client API. It is shown only in this response, so store it securely on the client and never log it. Write-only.
`client_api_url`	`string`	yes	Base URL of the Client API that accepts `access_token`. Allowed values: `"https://client-api.cloud.beeos.ai/v1"` — The production Client API.
`expires_at`	`string`	yes	Actual expiration of the issued token, capped by the remaining session authorization lifetime. Constraints: `format=date-time`.
`session_id`	`string`	yes	ID of the client session. Use it to refresh or revoke the session. Refreshing issues a new token for the same session.
`app_id`	`string`	yes	ID of the app the session belongs to.
`external_user_id`	`string`	yes	Unused. Cloud does not accept an external user id. Stored sessions leave this empty.
`capabilities`	`array<string>`	yes	Operations the token may perform on the Client API. They are the requested capabilities, without duplicates.
`binding`	Binding	yes	How the token is bound to the client, as requested when the session was created.

Errors

Status	Schema	Description
other (default)	ErrorResponse	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.identity.refreshClientSession("session_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.deleteExternalUser

DELETE /v1/external-users/{externalUserId} · Operation ID deleteExternalUser

Start external user data deletion

Idempotency-Key is required.

SDK methods

Language	Method	Signature
TypeScript	`cloud.identity.deleteExternalUser`	`deleteExternalUser(externalUserId: string, idempotencyKey: string): Promise<Models.DeleteExternalUserResponse>`
Python	`cloud.identity.delete_external_user`	`def delete_external_user(self, external_user_id: ExternalUserID, options: DeleteExternalUserOptions) -> DeletionAccepted`
Go	`cloud.Identity.DeleteExternalUser`	`func (r *IdentityResource) DeleteExternalUser(ctx context.Context, externalUserId ExternalUserID, options DeleteExternalUserOptions) (DeletionAccepted, error)`

Parameters

Parameter	In	Type	Required	Description
`externalUserId`	path	ExternalUserID	yes	ID of the end user whose stored data is deleted. 1 to 128 characters; `.` and `..` are rejected. This is the path resource id, not a request header.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=1`, `maxLength=256`.

Response

202 Asynchronous deletion accepted · application/json · Schema: DeletionAccepted

Field	Type	Required	Description
`deletion_id`	`string`	yes	ID of the deletion. Use it to read the progress of the deletion.
`status`	`string`	yes	State of the deletion when the request was accepted. Allowed values: `"pending"` — The deletion is queued and has not started; `"processing"` — The deletion is running; `"failed"` — The latest attempt stopped with an error, shown in `error_code`. The deletion is retried automatically; `"completed"` — All data of the user was deleted. (enum table)

Errors

Status	Schema	Description
other (default)	ErrorResponse	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.identity.deleteExternalUser("external_user_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.getExternalUserDeletion

GET /v1/external-users/{externalUserId}/deletions/{deletionId} · Operation ID getExternalUserDeletion

Get an external user data deletion

Idempotency-Key must not be sent.

SDK methods

Language	Method	Signature
TypeScript	`cloud.identity.getExternalUserDeletion`	`getExternalUserDeletion(externalUserId: string, deletionId: string): Promise<Models.GetExternalUserDeletionResponse>`
Python	`cloud.identity.get_external_user_deletion`	`def get_external_user_deletion(self, external_user_id: ExternalUserID, deletion_id: str) -> Deletion`
Go	`cloud.Identity.GetExternalUserDeletion`	`func (r *IdentityResource) GetExternalUserDeletion(ctx context.Context, externalUserId ExternalUserID, deletionId string) (Deletion, error)`

Parameters

Parameter	In	Type	Required	Description
`externalUserId`	path	ExternalUserID	yes	ID of the end user whose stored data is deleted. 1 to 128 characters; `.` and `..` are rejected. This is the path resource id, not a request header.
`deletionId`	path	`string`	yes	ID of the deletion, the `deletion_id` returned by the delete operation.

Response

200 Deletion progress scoped to the authenticated app · application/json · Schema: Deletion

Field	Type	Required	Description
`id`	`string`	yes	ID of the deletion.
`status`	`string`	yes	State of the deletion. Poll until it is `completed`. Allowed values: `"pending"` — The deletion is queued and has not started; `"processing"` — The deletion is running; `"failed"` — The latest attempt stopped with an error, shown in `error_code`. The deletion is retried automatically; `"completed"` — All data of the user was deleted. (enum table)
`deleted_resources`	`map<string, integer>`	yes	Number of items deleted so far, as an object that maps a kind of data to a count. The counts are final when `status` is `completed`. Kinds can be added, so do not depend on a fixed set of keys.

Errors

Status	Schema	Description
other (default)	ErrorResponse	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.identity.getExternalUserDeletion("external_user_123", "deletion_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

ClientSessionInput by client_type

The structure of ClientSessionInput depends on its own client_type value.

Value of client_type	Description	Structure
`"web"`	A browser client. The token is bound to the page origin you send in `origin`, which must be one of the allowed origins configured for the app. `device_attestation` must not be sent. A request that does not match this binding returns 403 `invalid_origin`.	ClientSessionInputWeb
`"native"`	A native app. The token is bound to a device key whose thumbprint you send in `device_attestation.jkt`. `origin` must not be sent. A request that does not match this binding returns 403 `invalid_origin`.	ClientSessionInputNative

BeeOS CloudBack to documentation