Authentication

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:

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

Scopes

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 — a backend job, a CI pipeline, or an AI agent — rather than a person. A service account carries an explicit permission list (not just a coarse read/read-write scope), so you can grant exactly the operations it needs and nothing more. Unlike a read-write user key, a least-privilege service account does not hold apikey:create/apikey:revoke, so it cannot mint further keys.

Create the account with its permissions, then mint a key bound to it:

bash
# 1) create the service accountcurl -sS -X POST https://api.b3os.org/v1/service-accounts \  -H "Authorization: Bearer YOUR_ADMIN_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "agent", "permissions": ["workflow:read", "workflow:execute", "run:read"] }'# 2) mint a key for it (serviceAccountId from the response above)curl -sS -X POST https://api.b3os.org/v1/api-keys \  -H "Authorization: Bearer YOUR_ADMIN_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "agent key", "serviceAccountId": "sa_123" }'

You can only delegate permissions you already hold. workflow:execute + run:read is the minimal set to run workflows and track their results.

With the minted key, execute a workflow and read the run it produces:

bash
# 3) execute a workflow (needs workflow:execute) — returns a runId immediatelycurl -sS -X POST https://api.b3os.org/v1/workflows/wf_123/run \  -H "Authorization: Bearer YOUR_SERVICE_ACCOUNT_KEY" \  -H "Content-Type: application/json" \  -d '{ "payload": { "asset": "USDC", "amount": "100" } }'# → { "data": { "runId": "run_abc" }, "code": 200, "message": "success" }# 4) read the run (needs run:read) — poll until status is terminalcurl -sS https://api.b3os.org/v1/runs/run_abc?summary=true \  -H "Authorization: Bearer YOUR_SERVICE_ACCOUNT_KEY"

See Workflows as Agent Tools for the full run → track → history loop and a permission matrix for exposing workflows as agent tool calls.

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

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 '{    "payload": {      "asset": "USDC",      "amount": "100"    }  }'