Client setup

Use this reference with the complete developer tour and TypeScript types. The example at the end runs after the tour setup.

call

Call a supported HTTP endpoint without a named SDK helper.

call<T>(method: string, path: string, body?: unknown, options?: { key?: string; signal?: AbortSignal; minimal?: boolean; }): Promise<T>

Parameter	Type and default	Usage
`method`	`string` (required)	HTTP verb, for example GET or POST.
`path`	`string` (required)	Supported /api/v1/ relative HTTP path, including any URL-encoded path/query values.
`body`	`unknown` (default optional)	Message or request content, bounded to 32 KiB of UTF-8 bytes.
`options`	`{ key?: string; signal?: AbortSignal; minimal?: boolean }` (default {})	Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism.

Returns: The endpoint’s JSON response; Go decodes into out. Use nil for ignored output.

Permissions, lifecycle and errors: Keep the /api/v1/ prefix. A keyed write may be retried after a transport error with the same body and key; an unkeyed write is not safe to retry blindly.

Declared return type: Promise<T>.

Working TypeScript example. Input/output fields are in the types reference.

connect

Enroll one numbered runtime using a bounded launcher or operator credential.

connect(agent: string, name: string, capabilities?: string[], metadata?: Record<string, unknown>, options?: { connection_name?: string; renewable?: boolean; expires_at?: string; never_expires?: boolean; }): Promise<{ client: Client; session: Session; }>

Parameter	Type and default	Usage
`agent`	`string` (required)	Stable agent external ID when enrolling; an Agent object in a Session response.
`name`	`string` (required)	Human-readable name. It is not necessarily unique.
`capabilities`	`string[]` (default [])	Application-declared runtime capabilities. This does not grant contact permission.
`metadata`	`Record<string, unknown>` (default {})	Application-supplied JSON metadata. Do not put credentials here.
`options`	`{connection_name?:string;renewable?:boolean;expires_at?:string;never_expires?:boolean}` (default {})	Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism.

Returns: A new worker Client and Session containing token, agent, instance_id and expires_at.

Permissions, lifecycle and errors: Enrollment is privileged. Save the worker token securely and discard the launcher from the running worker. Existing worker tokens construct Client directly.

Declared return type: Promise<{ client: Client; session: Session; }>.

Working TypeScript example. Input/output fields are in the types reference.

credentials

List authorized token metadata.

credentials(): Promise<Credential[]>

Parameter	Type and default	Usage

Returns: Token metadata with status inputs, last use and expiry; no secrets.

Permissions, lifecycle and errors: Never print secrets. Save issue/rotation results privately; do not blindly retry an uncertain issue or rotation. Edit and rotation require the current metadata version.

Declared return type: Promise<Credential[]>.

Working TypeScript example. Input/output fields are in the types reference.

createCredential

Issue a named, optionally restricted API or enrollment token.

createCredential(input: CredentialInput): Promise<IssuedCredential>

Parameter	Type and default	Usage
`input`	`CredentialInput` (required)	Typed operation input. See its declaration in the language types reference.

Returns: The new token secret once, id, kind and expires_at.

Declared return type: Promise<IssuedCredential>.

Working TypeScript example. Input/output fields are in the types reference.

editCredential

Edit name, expiry or API permission ceiling using the observed version.

editCredential(id: string, input: CredentialEdit): Promise<Credential>

Parameter	Type and default	Usage
`id`	`string` (required)	Existing stable resource ID, returned by the corresponding create/read operation.
`input`	`CredentialEdit` (required)	Typed operation input. See its declaration in the language types reference.

Returns: Current token metadata with its next version.

Declared return type: Promise<Credential>.

Working TypeScript example. Input/output fields are in the types reference.

rotateCredential

Replace a secret with a bounded overlap while retaining its instance.

rotateCredential(id: string, version: number, overlapSeconds?: number): Promise<CredentialReplacement>

Parameter	Type and default	Usage
`id`	`string` (required)	Existing stable resource ID, returned by the corresponding create/read operation.
`version`	`number` (required)	Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts.
`overlapSeconds`	`number` (default 3600)	How long the previous token remains usable after rotation, from zero to 86400 seconds. Defaults to 3600.

Returns: New token once and current metadata including previous_until.

Declared return type: Promise<CredentialReplacement>.

Working TypeScript example. Input/output fields are in the types reference.

revokeCredential

Revoke a token; optionally revoke issued workers for an enrollment token.

revokeCredential(id: string, revokeWorkers?: boolean): Promise<{ revoked: true; }>

Parameter	Type and default	Usage
`id`	`string` (required)	Existing stable resource ID, returned by the corresponding create/read operation.
`revokeWorkers`	`boolean` (default false)	Also revoke worker credentials enrolled through this credential.

Returns: Revocation acknowledgment; Go returns an error only.

Declared return type: Promise<{ revoked: true; }>.

Working TypeScript example. Input/output fields are in the types reference.

renewCredential

Renew a live worker lease within its hard deadline.

renewCredential(): Promise<Credential>

Parameter	Type and default	Usage

Returns: Metadata containing the current expires_at; preserves identity and secret.

Declared return type: Promise<Credential>.

Working TypeScript example. Input/output fields are in the types reference.

Example

Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.

import assert from 'node:assert/strict';
import { readFileSync, statSync } from 'node:fs';
import { Client, type Target, type Message } from '../../sdk/typescript/dist/index.js';

function readObject(value: unknown): Record<string, unknown> {
  assert.ok(value && typeof value === 'object');
  return value as Record<string, unknown>;
}

const credential = process.env.BEEPGRID_TOKEN_FILE;
assert.ok(credential && process.env.BEEPGRID_URL, 'Set BEEPGRID_TOKEN_FILE and BEEPGRID_URL');
assert.equal(statSync(credential).mode & 0o077, 0, 'Use chmod 600');
const owner = new Client(process.env.BEEPGRID_URL, readFileSync(credential, 'utf8').trim());
const runId = crypto.randomUUID();
const personId = (await owner.call<{person:{id:string}}>('GET', '/api/v1/me')).person.id;
const { client: builder, session: builderSession } = await owner.connect(`tour/${runId}/builder`, 'Builder 7');
const { client: billing, session: billingSession } = await owner.connect(`tour/${runId}/billing`, 'Billing 2');
const builderId = builderSession.agent.id, billingId = billingSession.agent.id;
for (const [agentId, peerId] of [[builderId, billingId], [billingId, builderId]]) {
  const rules = [['person', personId], ['agent', peerId]].flatMap(([kind, id]) =>
    ['view', 'message', 'ask'].map(action => ({ action, target_kind: kind, target_id: id })));
  const role = await owner.call<{id:string}>('POST', '/api/v1/roles', { name: `${runId}/${agentId}`, rules });
  await owner.call('POST', '/api/v1/role-bindings', { role_id: role.id, subject_kind: 'principal', subject_id: agentId });
}
const target: Target = { kind: 'agent', id: billingId };
const targets: Target[] = [{ kind: 'agent', id: builderId }, target];

const issued = await owner.createCredential({principal_id: builderId, kind: 'api', name: 'Tour key', never_expires: true, permissions: ['read']});
const keyMetadata = (await owner.credentials()).find(item => item.id === issued.id)!;
const edited = await owner.editCredential(issued.id, {version: keyMetadata.version, name: 'Renamed tour key'});
const rotated = await owner.rotateCredential(issued.id, edited.version, 0);
assert.equal(rotated.credential.id, issued.id);
await owner.revokeCredential(issued.id);
const {client: lease} = await owner.connect(`tour/${runId}/lease`, 'Lease example', [], {},
  {renewable: true, expires_at: new Date(Date.now() + 2 * 86400000).toISOString()});
assert.ok((await lease.renewCredential()).renewable_until);

Read this page as Markdown