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

# Authentication

> A bearer key bound to one workspace, which is why no request carries a tenant id.

## The header

```bash theme={null}
curl https://api.sigmora.org/v1/capabilities \
  -H "Authorization: Bearer sk_live_..."
```

Mint a key in the dashboard under **Settings → API keys**. It is shown once —
store it as `SIGMORA_API_KEY`.

## Why there is no workspace in the path

The key *is* the tenant. Putting a workspace id in the URL would mean a key
holder could name a workspace, and every route would then have to prove that key
may act for it — an impersonation surface with no upside. The workspace is
resolved from the credential instead, and cannot be overridden.

<Warning>
  A conflicting workspace header is **refused, not ignored**. Ignoring it would
  be safe but silent; refusing surfaces a client bug or an impersonation attempt
  rather than quietly doing something other than what you asked.
</Warning>

## Roles

| Operation                                                 | Minimum role |
| --------------------------------------------------------- | ------------ |
| Reads (`capabilities`, `usage`, `jobs`, listing projects) | `viewer`     |
| Anything that generates or spends credits                 | `editor`     |

Checking your own usage never requires a key that can spend.

## Where a key is valid

A workspace key opens `/v1` and nothing else. The engine behind it serves an
internal surface as well — the unpriced routes our own frontends call — and a
`sk_live_…` key is refused there with `403 forbidden`, naming `/v1` as the place
the credential belongs. There is no path that runs a priced capability without
pricing it.

## Rotation and containment

Keys are stored hashed, never recoverably — losing one means minting a
replacement, not retrieving the original. Revocation takes effect immediately.

<Note>
  **A key cannot mint another key.** Key management is a session-only surface, so
  a leaked key cannot be used to establish persistence.
</Note>