---
title: Authentication
description: "Bearer tokens, scopes, and security model."
canonical: https://bennybooks.com/developers/authentication
markdown: https://bennybooks.com/developers/authentication.md
---
# Authentication

Bearer tokens, scopes, and security model.

> **Documentation index.** Fetch [https://bennybooks.com/developers/llms.txt](https://bennybooks.com/developers/llms.txt) before browsing further. Prefer markdown (this file or `Accept: text/markdown`). Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

Protected routes under /api/mcp (Streamable HTTP MCP) and https://bennybooks.com/api/v1 require a valid BennyBooks API token in the Authorization header. Public discovery (OpenAPI, ontology, https://bennybooks.com/llms.txt, https://bennybooks.com/developers) needs no token.

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

> **Preferred agent path.** Point your MCP host at /api/mcp with this bearer header. Setup: Guides → Connect Streamable HTTP MCP (or npx @bennybooks/cli agent setup).

## Token format

- Prefix: bb_live_
- Stored as SHA-256 hash — plaintext shown only once at creation
- Org-scoped — tied to the Clerk organization active when created
- Revocable from Settings → MCP & agents
- Same token works for /api/mcp, REST https://bennybooks.com/api/v1, and OpenAPI bridges

## Scopes

| Scope | Access |
| --- | --- |
| read | MCP read tools + authenticated GET under https://bennybooks.com/api/v1 |
| propose-write | MCP write tools + POST/PUT proposal endpoints (includes read) |

> **Public endpoints.** GET https://bennybooks.com/openapi.json, GET https://bennybooks.com/api/v1/ontology.jsonld, GET https://bennybooks.com/api/v1/ontology.ttl, GET https://bennybooks.com/api/v1/ontology/context.jsonld, GET|POST https://bennybooks.com/api/v1/ontology/sparql, https://bennybooks.com/llms.txt, https://bennybooks.com/agents.txt, https://bennybooks.com/skill.md, https://bennybooks.com/auth.md, and https://bennybooks.com/developers are public (no token). /api/mcp itself requires a bearer token.

> **Pro plan.** When billing enforcement is enabled (BILLING_ENFORCEMENT=true), propose-write tokens require a Pro subscription.

---

## Machine-readable

- HTML: https://bennybooks.com/developers/authentication
- Markdown: https://bennybooks.com/developers/authentication.md
- Docs index: https://bennybooks.com/developers/llms.txt
- OpenAPI: https://bennybooks.com/openapi.json
- Skill: https://bennybooks.com/skill.md
- Auth: https://bennybooks.com/auth.md

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Authentication",
  "description": "Bearer tokens, scopes, and security model.",
  "url": "https://bennybooks.com/developers/authentication",
  "inLanguage": "en",
  "encodingFormat": [
    "text/html",
    "text/markdown"
  ],
  "isAccessibleForFree": true,
  "publisher": {
    "@type": "Organization",
    "name": "BennyBooks",
    "url": "https://bennybooks.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://bennybooks.com/apple-icon.png"
    }
  },
  "mainEntityOfPage": "https://bennybooks.com/developers/authentication",
  "image": "https://bennybooks.com/opengraph-image",
  "workExample": {
    "@type": "CreativeWork",
    "url": "https://bennybooks.com/developers/authentication.md",
    "encodingFormat": "text/markdown",
    "name": "Authentication (Markdown)"
  },
  "about": {
    "@type": "WebAPI",
    "name": "BennyBooks Agent API",
    "url": "https://bennybooks.com/api/v1",
    "documentation": "https://bennybooks.com/developers"
  }
}
```
