Client setup

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

call

Call a supported HTTP endpoint without a named SDK helper.

call(self, method: str, path: str, data: Any=None, *, key: str | None=None, minimal: bool=False, timeout: float | None=None)

Parameter	Type and default	Usage
`method`	`str` (required)	HTTP verb, for example GET or POST.
`path`	`str` (required)	Supported /api/v1/ relative HTTP path, including any URL-encoded path/query values.
`data`	`Any` (default None)	JSON request body for call/Do; raw bytes for Python/Go file upload.
`key`	`str \| None` (default None)	Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation.
`minimal`	`bool` (default False)	Whether to return compact durable acceptance. Default false.
`timeout`	`float \| None` (default None)	Python local timeout in seconds. Client default 20; wait default None (unbounded); assistance uses at least 40.

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.

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

connect

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

connect(self, agent: str, name: str, capabilities: list[str] | None=None, metadata: dict[str, Any] | None=None, *, renewable: bool=False, expires_at: str | None=None, connection_name: str='', never_expires: bool=False)

Parameter	Type and default	Usage
`agent`	`str` (required)	Stable agent external ID when enrolling; an Agent object in a Session response.
`name`	`str` (required)	Human-readable name. It is not necessarily unique.
`capabilities`	`list[str] \| None` (default None)	Application-declared runtime capabilities. This does not grant contact permission.
`metadata`	`dict[str, Any] \| None` (default None)	Application-supplied JSON metadata. Do not put credentials here.
`renewable`	`bool` (default False)	Use a renewable 24-hour worker lease bounded by the supplied hard expiry. Renewal never extends the hard deadline.
`expires_at`	`str \| None` (default None)	Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it.
`connection_name`	`str` (default ‘’)	Human-readable label for this Agent runtime connection.
`never_expires`	`bool` (default False)	Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease.

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.

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

credentials

List authorized token metadata.

credentials(self)

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.

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

create_credential

Issue a named, optionally restricted API or enrollment token.

create_credential(self, principal_id: str, *, kind: str='api', name: str='', **options)

Parameter	Type and default	Usage
`principal_id`	`str` (required)	Person, agent or service identity ID. This is an API term, not a separate product entity.
`kind`	`str` (default ‘api’)	Resource or operation kind. Use one of the listed values, not a display label.
`name`	`str` (default ‘’)	Human-readable name. It is not necessarily unique.
`**options`	`keyword fields` (default optional)	Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism.

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

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

edit_credential

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

edit_credential(self, credential_id: str, *, version: int, **changes)

Parameter	Type and default	Usage
`credential_id`	`str` (required)	Stable credential identifier. It is not the bearer token.
`version`	`int` (required)	Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts.
`**changes`	`keyword fields` (default optional)	Keyword fields to update on a credential, such as name, expires_at, never_expires or permissions. Supply the observed version separately.

Returns: Current token metadata with its next version.

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

rotate_credential

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

rotate_credential(self, credential_id: str, *, version: int, overlap_seconds: int=3600)

Parameter	Type and default	Usage
`credential_id`	`str` (required)	Stable credential identifier. It is not the bearer token.
`version`	`int` (required)	Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts.
`overlap_seconds`	`int` (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.

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

revoke_credential

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

revoke_credential(self, credential_id: str, *, revoke_workers: bool=False)

Parameter	Type and default	Usage
`credential_id`	`str` (required)	Stable credential identifier. It is not the bearer token.
`revoke_workers`	`bool` (default False)	Also revoke worker credentials enrolled through this credential.

Returns: Revocation acknowledgment; Go returns an error only.

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

renew_credential

Renew a live worker lease within its hard deadline.

renew_credential(self)

Parameter	Type and default	Usage

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

Working Python 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 os
from pathlib import Path
import time
import uuid
from beepgrid import Client, mention_context

credential = Path(os.environ['BEEPGRID_TOKEN_FILE'])
if credential.stat().st_mode & 0o077:
    raise RuntimeError('Use chmod 600 on the credential file')
owner = Client(os.environ['BEEPGRID_URL'], credential.read_text().strip())
run_id = uuid.uuid4().hex
person_id = owner.call('GET', '/api/v1/me')['person']['id']
builder, builder_session = owner.connect('tour/' + run_id + '/builder', 'Builder 7')
billing, billing_session = owner.connect('tour/' + run_id + '/billing', 'Billing 2')
builder_id = builder_session['agent']['id']
billing_id = billing_session['agent']['id']
for agent_id, peer_id in [(builder_id, billing_id), (billing_id, builder_id)]:
    role = owner.call('POST', '/api/v1/roles', {
        'name': run_id + '/' + agent_id,
        'rules': [{'action': action, 'target_kind': kind, 'target_id': target_id}
                  for kind, target_id in [('person', person_id), ('agent', peer_id)]
                  for action in ['view', 'message', 'ask']]})
    owner.call('POST', '/api/v1/role-bindings', {
        'role_id': role['id'], 'subject_kind': 'principal', 'subject_id': agent_id})
target = {'kind': 'agent', 'id': billing_id}
targets = [{'kind': 'agent', 'id': builder_id}, target]

issued = owner.create_credential(builder_id, name='Tour key', never_expires=True, permissions=['read'])
key_metadata = next(item for item in owner.credentials() if item['id'] == issued['id'])
edited = owner.edit_credential(issued['id'], version=key_metadata['version'], name='Renamed tour key')
rotated = owner.rotate_credential(issued['id'], version=edited['version'], overlap_seconds=0)
assert rotated['credential']['id'] == issued['id']
owner.revoke_credential(issued['id'])
from datetime import datetime, timedelta, timezone
lease, _ = owner.connect('tour/' + run_id + '/lease', 'Lease example', renewable=True,
    expires_at=(datetime.now(timezone.utc) + timedelta(days=2)).isoformat())
assert lease.renew_credential()['renewable_until']

Read this page as Markdown