# Authenticating with the PivotBank API

PivotBank's API uses long-lived API keys, not OAuth. There is one endpoint, `POST https://pivotbank.app/api/v1/convert`, and one credential type, a bearer key that a signed-in Pro user creates. This page follows the auth.md layout (agent_auth) so an agent can find each step, and says plainly where a step does not apply.

## Discover

- Spec: https://pivotbank.app/openapi.json (security scheme `apiKey`, HTTP bearer).
- Catalog: https://pivotbank.app/.well-known/api-catalog
- There is no `identity_endpoint`, no `identity_assertion` and no `service_auth` flow. There is no authorization server, so `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` are not published. `id-jag` assertions are not accepted.
- A request without a key gets `401` with `WWW-Authenticate: Bearer realm="PivotBank API"` and a JSON body naming the fix.

## Pick a method

One method: an API key sent as a bearer token. `Authorization: Bearer pvb_live_...` is preferred; `x-api-key: pvb_live_...` is also read.

## Register

An agent cannot register itself. A person signs in at https://pivotbank.app/auth/signin, holds an active Pro subscription (https://pivotbank.app/pricing), and creates a key at https://pivotbank.app/account/api-keys. Up to a handful of keys per account, each named so it can be revoked on its own.

## Claim

The raw key is shown once, at creation, and only its SHA-256 hash is stored. Copy it into the agent's secret store at that moment; it cannot be retrieved again. A lost key is revoked and replaced.

## Exchange

No exchange step. The key is the access token. It does not expire and is not refreshed; it stops working the moment it is revoked or the subscription lapses.

## Use the access_token

```
curl -X POST https://pivotbank.app/api/v1/convert \
  -H "Authorization: Bearer pvb_live_..." \
  -F "file=@statement.pdf"
```

Or send the PDF as the body with `Content-Type: application/pdf`. The response is JSON; read `reconciliation.verified` before trusting the rows, and `X-Pages-Left` to see how much of the month's allowance remains.

## Errors

All errors are JSON: `{ "error": "<sentence>", "code": "<code>" }`.

| Status | code | Meaning |
|---|---|---|
| 401 | `missing_key` | No `Authorization` or `x-api-key` header. |
| 401 | `invalid_key` | Unknown or revoked key. |
| 403 | `pro_required` | The key's account has no active Pro subscription. |
| 402 | `no_pages_left` | The month's pages are spent. `X-Pages-Left: 0`. Top up at https://pivotbank.app/account/billing. |
| 400 | `no_file`, `unreadable`, `empty` | Nothing usable in the request body. |
| 413 | `too_large` | Over 15 MB, judged before the body is read. |
| 422 | `unparseable` | Not a readable PDF, or a scan with no text layer. Nothing is charged. |

## Revocation

A key is revoked at https://pivotbank.app/account/api-keys by the account holder. Revocation is immediate; the next request with that key gets `401 invalid_key`. Cancelling the Pro subscription leaves keys in place but every request gets `403 pro_required` until it is renewed.
