Authentication

Authenticate to the B3OS API with user sessions, API keys, service accounts, and organization context.

B3OS supports human user sessions for the app and scoped API keys for backend automation. API keys are the recommended path for server-to-server integrations.

Bearer Authentication

Send credentials in the Authorization header:

http
Authorization: Bearer YOUR_API_KEY

API Keys

API keys:

PropertyBehavior
PrefixRaw keys use the b3sk_ prefix
StorageB3OS stores hashes, not raw keys
RevealThe raw key is shown once at creation
ScopeKeys are scoped, commonly read or read-write
RevocationKeys can be revoked without deleting historical records
OrganizationKeys are associated with an organization context

Copy the key into a secret manager immediately. B3OS cannot retrieve and display the raw key later.

Scopes

ScopeIntended use
readDashboards, reporting, status checks, run inspection, workflow inventory
read-writeBackend automation that creates, updates, publishes, or executes workflows and manages related operational resources

read-write grants broad build and operate capabilities. Use separate keys per service so rotation and auditing are straightforward.

Organization Context

API keys are bound to organization access. User-session requests may also require explicit organization context depending on the route and app state.

When an endpoint requires an organization header, send:

http
X-Org-ID: org_123

For server-to-server integrations, prefer organization-scoped API keys over reusing browser session credentials.

Service Accounts

Use service accounts when the actor is a system rather than a person. Pair each service account with keys scoped to the minimum operations it needs.

Safe Key Practices

  1. Create one key per service or environment.
  2. Store keys in a secret manager.
  3. Never expose keys in browser or client bundles.
  4. Rotate keys when ownership or deployment access changes.
  5. Revoke unused keys.
  6. Use read keys for dashboards and reporting.
  7. Use read-write keys only when automation needs writes or execution.

Example Request

Run a workflow 
bash
curl -X POST https://api.b3os.org/v1/workflows/wf_123/run \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "asset": "USDC",      "amount": "100"    }  }'
Previous API Overview
Next Execution Hooks