> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Property     | Behavior                                                |
| ------------ | ------------------------------------------------------- |
| Prefix       | Raw keys use the `b3sk_` prefix                         |
| Storage      | B3OS stores hashes, not raw keys                        |
| Reveal       | The raw key is shown once at creation                   |
| Scope        | Keys are scoped, commonly `read` or `read-write`        |
| Revocation   | Keys can be revoked without deleting historical records |
| Organization | Keys are associated with an organization context        |

**One-time reveal**

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

## Scopes

| Scope        | Intended use                                                                                                         |
| ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `read`       | Dashboards, reporting, status checks, run inspection, workflow inventory                                             |
| `read-write` | Backend 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
```

**API key integrations usually do not need user context**

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 account
curl -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 immediately
curl -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 terminal
curl -sS https://api.b3os.org/v1/runs/run_abc?summary=true \
  -H "Authorization: Bearer YOUR_SERVICE_ACCOUNT_KEY"
```

**Building an agent?**

See [Workflows as Agent Tools](/platform/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

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