# auth.md

How to authenticate with bolthub, written for agents.

## Short version

**Buying an API call needs no account, no registration and no API key.** Paid
endpoints answer an unauthenticated request with HTTP 402 and a Lightning
invoice. Pay it, retry with the receipt, and you are through. The credential is
the payment; it is minted per request and belongs to whoever paid.

Registration exists only for *sellers* (people listing an API and collecting the
sats), and that path runs through a human sign-in at https://bolthub.ai/signup.

## Audience

| You are | You need |
| --- | --- |
| An agent calling a listed API | Nothing up front. Pay the 402 challenge. |
| An agent reading the directory | Nothing. Discovery is public. |
| A seller's backend verifying payments | A facilitator API key. |
| A script driving the platform API | A personal access token. |

## Methods

### 1. None (public discovery)

The directory, catalog and per-listing descriptions are unauthenticated:

```http
GET https://api.bolthub.ai/directory
GET https://bolthub.ai/.well-known/api-catalog
GET https://{slug}.gw.bolthub.ai/.well-known/openapi.json
```

### 2. L402 (paid API calls)

Bearer method: `header`. The flow is two requests:

```http
GET /v1/example HTTP/1.1
Host: {slug}.gw.bolthub.ai

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="MDAxM...", invoice="lnbc50n1..."
```

Pay the Lightning invoice, take the payment preimage, and retry:

```http
GET /v1/example HTTP/1.1
Host: {slug}.gw.bolthub.ai
Authorization: L402 MDAxM...:9f86d081...
```

The macaroon is the server's token, the preimage is proof you paid it. Together
they are the credential. Reuse depends on the endpoint's pricing model: a
per-request price buys one call, a time pass or token bucket keeps working until
it is spent.

Clients that do this for you: `npx @bolthub/mcp` (MCP), `npm install
@bolthub/pay` (TypeScript), `pip install bolthub` (Python).

### 3. Bearer token (platform API)

Human-owned resources on `https://api.bolthub.ai` take a bearer token in the
`Authorization` header:

```http
Authorization: Bearer bh_pat_...
```

Accepted tokens are a personal access token (prefix `bh_pat_`) or a session
JWT. Personal access tokens are issued from the dashboard at https://bolthub.ai/keys and
are shown once. Scope is the workspace the token belongs to; there is no
self-service registration endpoint that mints one.

### 4. Bearer key (hosted facilitator)

A seller's backend verifying payments server-to-server uses its facilitator API
key (prefix `blt_`), also as a bearer token:

```http
Authorization: Bearer blt_...
```

Keys are issued from the dashboard and identify the selling workspace.

## Not offered

- **OAuth 2.0 / OIDC.** There is no authorization server for agents, so no
  `/.well-known/oauth-protected-resource` and no
  `/.well-known/oauth-authorization-server` are published. If that changes,
  this file changes with it.
- **Dynamic client registration.** Nothing to register: payment is the
  credential.
- **Anonymous identity assertions.** L402 already gives an agent access without
  an identity, which is the property those flows are usually reaching for.

## More

- Paying for calls: https://docs.bolthub.ai/docs/guides/using-paywalled-apis
- Agent wallet security: https://docs.bolthub.ai/docs/guides/agent-wallet-security
- Machine-readable catalog: https://bolthub.ai/.well-known/api-catalog
- Contact: contact@bolthub.ai