# The /v1 API

> BatonDeck's REST API: 109 operations, generated from the route table the router mounts.

The API the BatonDeck portal is built on, and the one a program talks to.

Two credentials. A browser sends the portal session cookie and, on anything that changes state, must be same-origin. A program sends `Authorization: Bearer <key>` — a workspace API key, minted in the portal, shown once. A key is never wider than the owner who minted it: its scopes narrow their permissions and can never widen them.

A key has no session, so it has no step-up: every operation marked as requiring one is refused to a key, whatever scopes it carries. Those are the irreversible ones — export, deletion, key rotation, changing who is in the workspace — and a person has to be present for them.

Webhooks. A workspace registers an endpoint with `POST /v1/workspace/webhooks`, naming the events it wants, and lists its endpoints with `GET /v1/workspace/webhooks`, which also answers the event names a filter may use. Each delivery is a JSON POST to the endpoint, signed in `X-BatonDeck-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>" under the endpoint's secret>` (two `v1` values while a rotated secret is still accepted), and carrying `X-BatonDeck-Event-Id`, `X-BatonDeck-Event-Type` and `X-BatonDeck-Delivery`. Nothing is delivered while the workspace's `webhooks_enabled` flag is off; the list says which it is, as `enabled`.

**Server:** `https://api.batondeck.com` · **OpenAPI:** [3.1.0 document](/batondeck-openapi.json) (109 operations; the same document the API serves at `https://api.batondeck.com/v1/openapi.json`).

## Credentials

| Scheme | How it is sent | Notes |
|---|---|---|
| `session` | cookie `__Host-bd_session` |  |
| `apiKey` | `Authorization: Bearer …` | A workspace API key: `bd_<id>_<secret>`. Minted by a person on the portal's Agents page (Agent keys), which calls `POST /v1/workspace/keys` with a session; a key cannot mint one, because minting needs step-up. Shown once, hashed at rest. Malformed, unknown and revoked keys answer identically. |

## Errors

Every refusal answers this body:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "description": "a stable machine-readable code; HDTP §12 names where a call maps to one",
          "type": "string"
        },
        "message": {
          "description": "what went wrong, in words a person can act on",
          "type": "string"
        },
        "request_id": {
          "description": "the same id that appears in our logs for this request",
          "type": "string"
        },
        "retry_after": {
          "description": "on a 429: seconds until the window closes, as the Retry-After header says",
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

## Calling it from a browser

The API answers cross-origin (CORS) requests only on `/mcp`, `/oauth/token`, `/oauth/register`, `/oauth/revoke`, `/.well-known/`. `/v1` is not among them, so a page on another origin — this one included — cannot call it, and this reference has no in-page "try it". Each operation shows the `curl` call instead.

## Operations

- [Factors](/cloud/api/factors/) — 4 operations
- [Identities](/cloud/api/identities/) — 3 operations
- [Identity: address](/cloud/api/identity-address/) — 1 operation
- [Identity: addresses](/cloud/api/identity-addresses/) — 3 operations
- [Identity: audit](/cloud/api/identity-audit/) — 1 operation
- [Identity: badges](/cloud/api/identity-badges/) — 1 operation
- [Identity: card](/cloud/api/identity-card/) — 1 operation
- [Identity: certificate](/cloud/api/identity-certificate/) — 1 operation
- [Identity: changes](/cloud/api/identity-changes/) — 1 operation
- [Identity: contacts](/cloud/api/identity-contacts/) — 14 operations
- [Identity: csr](/cloud/api/identity-csr/) — 1 operation
- [Identity: digest](/cloud/api/identity-digest/) — 1 operation
- [Identity: export](/cloud/api/identity-export/) — 2 operations
- [Identity: grants](/cloud/api/identity-grants/) — 3 operations
- [Identity: import](/cloud/api/identity-import/) — 5 operations
- [Identity: inbox](/cloud/api/identity-inbox/) — 1 operation
- [Identity: integrations](/cloud/api/identity-integrations/) — 6 operations
- [Identity: invites](/cloud/api/identity-invites/) — 4 operations
- [Identity: leaf](/cloud/api/identity-leaf/) — 1 operation
- [Identity: media](/cloud/api/identity-media/) — 1 operation
- [Identity: messages](/cloud/api/identity-messages/) — 2 operations
- [Identity: pending](/cloud/api/identity-pending/) — 2 operations
- [Identity: presets](/cloud/api/identity-presets/) — 2 operations
- [Identity: settings](/cloud/api/identity-settings/) — 2 operations
- [Identity: storage](/cloud/api/identity-storage/) — 1 operation
- [Identity: threads](/cloud/api/identity-threads/) — 4 operations
- [Identity: wallet request](/cloud/api/identity-wallet-request/) — 2 operations
- [Integrations](/cloud/api/integrations/) — 1 operation
- [Presets](/cloud/api/presets/) — 1 operation
- [Sessions](/cloud/api/sessions/) — 3 operations
- [Statuses](/cloud/api/statuses/) — 1 operation
- [Workspace](/cloud/api/workspace/) — 2 operations
- [Workspace: audit](/cloud/api/workspace-audit/) — 1 operation
- [Workspace: billing](/cloud/api/workspace-billing/) — 3 operations
- [Workspace: deletion](/cloud/api/workspace-deletion/) — 2 operations
- [Workspace: domains](/cloud/api/workspace-domains/) — 5 operations
- [Workspace: export](/cloud/api/workspace-export/) — 1 operation
- [Workspace: keys](/cloud/api/workspace-keys/) — 3 operations
- [Workspace: members](/cloud/api/workspace-members/) — 1 operation
- [Workspace: pause](/cloud/api/workspace-pause/) — 2 operations
- [Workspace: plan](/cloud/api/workspace-plan/) — 1 operation
- [Workspace: residency](/cloud/api/workspace-residency/) — 1 operation
- [Workspace: settings](/cloud/api/workspace-settings/) — 1 operation
- [Workspace: sso](/cloud/api/workspace-sso/) — 3 operations
- [Workspace: usage](/cloud/api/workspace-usage/) — 1 operation
- [Workspace: webhooks](/cloud/api/workspace-webhooks/) — 6 operations