# Meta

Your key and its workspace.

Two calls that need no scope, so any working key may make them. Use them while
you are setting an integration up, and as a liveness probe afterwards.

`GET /v1/ping` answers with the scopes the key carries, and `lost_scopes`: the
scopes it was issued with that its creator no longer stands behind. Anything in
that array means the key is quietly doing less than it was created to do. See
[A key never does more than the person who created it](https://boltclaw.ai/docs/authentication#a-key-never-does-more-than-the-person-who-created-it).

`GET /v1/workspace` answers with the workspace the key belongs to. Every key
belongs to exactly one, so no other call in this API takes a workspace
parameter, and this is the only response that names one.

## Operations

### `GET /v1/ping`

**Check a key**

No scope: any valid key.

The cheapest authenticated call: confirms the key works and returns the scopes it carries.
Needs no scope. Use it during setup and as a liveness probe.

**Answers**

| Status | Body |  |
|---|---|---|
| 200 | `Ping` | The key is valid. |
| 401 | `ErrorEnvelope` | `UNAUTHORIZED`: no key, or one that is malformed, unknown or revoked. It never says which. |
| 403 | `ErrorEnvelope` | `INSUFFICIENT_SCOPE`: the key lacks this operation's scope. Or `ORGANISATION_SUSPENDED`: the key's organisation is suspended. Never about another workspace's object, which is 404. |
| 429 | `ErrorEnvelope` | `RATE_LIMITED`: too many requests. Wait for `Retry-After` seconds. |
| 500 | `ErrorEnvelope` | `INTERNAL_ERROR`: ours. Safe to retry; send the same `Idempotency-Key` on a POST. |

### `GET /v1/workspace`

**Read the key's workspace**

No scope: any valid key.

The workspace this key belongs to: its id and its name. Needs no scope. The id appears in
no other response; it is how you tell two keys apart.

**Answers**

| Status | Body |  |
|---|---|---|
| 200 | `Workspace` | The key's workspace. |
| 401 | `ErrorEnvelope` | `UNAUTHORIZED`: no key, or one that is malformed, unknown or revoked. It never says which. |
| 403 | `ErrorEnvelope` | `INSUFFICIENT_SCOPE`: the key lacks this operation's scope. Or `ORGANISATION_SUSPENDED`: the key's organisation is suspended. Never about another workspace's object, which is 404. |
| 429 | `ErrorEnvelope` | `RATE_LIMITED`: too many requests. Wait for `Retry-After` seconds. |
| 500 | `ErrorEnvelope` | `INTERNAL_ERROR`: ours. Safe to retry; send the same `Idempotency-Key` on a POST. |

**Which workspace is this key for?** — answers `200`

The only response in the API that names a workspace. Every key belongs to exactly one, so nothing else needs to ask.

```bash
curl https://api.boltclaw.ai/v1/workspace \
  -H "Authorization: Bearer bc_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

```js
const res = await fetch("https://api.boltclaw.ai/v1/workspace", {
  headers: {
    Authorization: `Bearer ${process.env.BOLTCLAW_KEY}`,
  },
});

// 200
const data = await res.json();
```

## Shapes

The objects these operations send and answer.

### Ping

| Field | Type |  |
|---|---|---|
| `pong` | `true` | (**required**) |
| `key_kind` | `string` | BoltClaw keys are secret keys, for servers. There are no browser keys. (**required**; one of `secret`) |
| `scopes` | `Scope[]` | What the key may do right now. (**required**) |
| `lost_scopes` | `Scope[]` | Scopes the key was issued with and no longer has, because the person who created it lost the permission behind them or left the workspace. Normally empty. Anything here explains a `403 INSUFFICIENT_SCOPE` on an operation the key was created for. (**required**) |

### Workspace

| Field | Type |  |
|---|---|---|
| `id` | `uuid` | (**required**) |
| `name` | `string` | (**required**) |

<!-- https://boltclaw.ai/docs/api/meta as markdown. Generated from openapi.yaml; API version 1.22.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->