---
name: bennybooks-auth
title: BennyBooks agent authentication
description: Authenticate to BennyBooks with org-scoped bb_live_ API tokens (not interactive OAuth). Use when connecting Streamable HTTP MCP at /api/mcp, @bennybooks/cli agent setup, or a REST/OpenAPI client.
---

# Auth for agents

BennyBooks does **not** use interactive OAuth for the agent API. Agents authenticate with org-scoped opaque API tokens created by a human in the product UI.

## Token

Create a token in **Settings → MCP & agents**. Tokens look like:

```
bb_live_<secret>
```

Send on every authenticated request to `/api/mcp` (Streamable HTTP MCP) or `/api/v1` (REST):

```http
Authorization: Bearer bb_live_<secret>
```

| Scope | Access |
| --- | --- |
| `read` | MCP read tools + authenticated GET under `/api/v1` |
| `propose-write` | Write tools / proposal endpoints (includes read) |

Tokens are always scoped to one organization. Never send `org_id` — the server derives tenancy from the token.

## Preferred: Streamable HTTP MCP

Endpoint: `https://bennybooks.com/api/mcp`

Use this URL in Cursor, Claude custom connectors, or any MCP host that supports remote Streamable HTTP. Pass the bearer token in the Authorization header. Setup: https://bennybooks.com/developers/guides/mcp-server.md

Resources `bennybooks://ontology` and `bennybooks://skill`, plus prompts `categorize` / `investigate` / `month-end`, are available on the same server.

Wire a host from the terminal (same token):

```bash
npx @bennybooks/cli auth set-token
npx @bennybooks/cli agent setup
```

CLI guide: https://bennybooks.com/developers/guides/cli.md

## Also supported: REST / OpenAPI bridge

Base URL: `https://bennybooks.com/api/v1` · OpenAPI: `https://bennybooks.com/openapi.json`

Import OpenAPI into AnythingMCP if you prefer a bridge: https://bennybooks.com/developers/guides/anythingmcp.md

## Public (no token)

- [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt)
- [https://bennybooks.com/openapi.json](https://bennybooks.com/openapi.json)
- [https://bennybooks.com/api/v1/ontology.jsonld](https://bennybooks.com/api/v1/ontology.jsonld)
- [https://bennybooks.com/api/v1/ontology.ttl](https://bennybooks.com/api/v1/ontology.ttl)
- [https://bennybooks.com/api/v1/ontology/sparql](https://bennybooks.com/api/v1/ontology/sparql) (static ontology SPARQL; not ledger)
- [https://bennybooks.com/skill.md](https://bennybooks.com/skill.md)
- [https://bennybooks.com/auth.md](https://bennybooks.com/auth.md) (this file)
- Developer docs under `/developers` (also as `.md` / `Accept: text/markdown`)

## Discovery metadata

| Document | URL |
| --- | --- |
| Protected resource (RFC 9728) | https://bennybooks.com/.well-known/oauth-protected-resource |
| Authorization server metadata | https://bennybooks.com/.well-known/oauth-authorization-server |
| MCP server card | https://bennybooks.com/.well-known/mcp/server-card.json |
| Streamable HTTP MCP | https://bennybooks.com/api/mcp |
| Agent skill | https://bennybooks.com/skill.md |
| OpenAPI | https://bennybooks.com/openapi.json |

`WWW-Authenticate` on `401` responses from `/api/mcp` and `/api/v1` points at the protected-resource metadata.

## How tokens are issued

1. A signed-in human opens Settings → MCP & agents
2. They create a token with `read` or `propose-write`
3. They paste the secret into their MCP host / bridge / agent config
4. There is no `authorization_endpoint` login flow for agents in v1 (OAuth CIMD is a future Directory path)

Human sign-in for the web app uses Clerk (session cookies). That path is for people in a browser, not for API agents.

## Writes and approval

`propose-write` creates **pending proposals**. Ledger rows change only after a human approves them in the UI. Every write is audit-logged in **Log** (`/log`) — there is no agent read API for Log in v1.

## More

- Skill: https://bennybooks.com/skill.md
- Native MCP: https://bennybooks.com/developers/guides/mcp-server.md
- Quickstart: https://bennybooks.com/developers/quickstart.md
- MCP bridge: https://bennybooks.com/developers/guides/anythingmcp.md