API authentication

How to authenticate with the AgentDocs API: browser sessions (JWT), account and space API tokens, or OAuth for MCP connectors.

Overview

AgentDocs accepts three kinds of credential. Choose by use case:

JWT authentication

Sign in to get a JWT, then send it with each request.

Step 1: Sign in

Send your email and password to the login endpoint:

curl -X POST https://agentdocs.eu/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "your_password"
  }'

# Response (200 OK):
{
  "user": {
    "id": "0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d",
    "email": "alice@example.com",
    "name": "Alice",
    "role": "user",
    "nostr_pubkey": null,
    "email_verified_at": "2026-10-01T09:12:00.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 2: Use the token

Include the JWT in the Authorization header of every API request:

curl https://agentdocs.eu/api/workspaces \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

API token authentication

API tokens are the recommended method for agents and scripts. An account token does not expire. To limit an agent to one space, use a space-scoped token (below).

Getting your API token

AgentDocs stores only a hash of your API token, so you see it once: in user.api_token when you register through the API, or when you create one in the web app. To create one:

1. Sign in at https://agentdocs.eu/login
2. On the dashboard, click your name in the top bar to open your Profile
3. Click Regenerate API Token and confirm. Your previous token stops working immediately.
4. Copy the token now. It is not shown again.

Using the API token

Include your token in the Authorization header using the Token scheme:

# API Token authentication
curl https://agentdocs.eu/api/workspaces \
  -H "Authorization: Token your_api_token_here"

# Create a page
curl -X POST https://agentdocs.eu/api/spaces/SPACE_ID/pages \
  -H "Authorization: Token your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Page", "content": "# Hello"}'

# Update a page
curl -X PUT https://agentdocs.eu/api/pages/PAGE_ID \
  -H "Authorization: Token your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Updated content"}'

Space-scoped tokens

A space token works only inside one space: the space itself, its pages, comments and share links. It uses the same header, Authorization: Token <token>. Workspace and account routes refuse it with 403 space_token_not_allowed. To create one, open the space and click Connect an agent, or click the key icon next to the space in the sidebar. You must be the workspace owner or a space admin. The token is shown once.

Each token has a permission. Read only (the default in the web app) refuses every change. Read and propose edits can only submit proposed changes for a person to approve. Read and edit directly works like an editor. Tokens created with POST /api/spaces/:spaceId/tokens get direct_edit unless you send a permission field.

An agent that only has a space token can call GET /api/auth/me to find out which space and workspace the token belongs to.

Token format comparison

OAuth 2.1 (MCP connectors)

AgentDocs runs a built-in OAuth 2.1 authorization server (RFC 8414 discovery, dynamic client registration, PKCE). You never copy a token — the whole flow is four steps:

1. In Claude, open Settings → Connectors → Add custom connector and enter https://agentdocs.eu/mcp
2. Leave Advanced settings empty — no OAuth Client ID, no secret, no headers.
3. Your browser opens the AgentDocs consent page: sign in and click Approve.
4. Done — Claude holds a documents-only credential you can revoke any time under Settings → Connected apps.

Share links (no auth)

Share links give read-only access to one page with no authentication at all. The token in the URL is the credential:

# No Authorization header
curl https://agentdocs.eu/api/shared/SHARE_TOKEN/raw

# Returns plain Markdown with YAML frontmatter

This is the simplest way to give an AI agent access to documentation. See the Working with agents guide for detailed examples.

Error responses

A failed request returns a status code and a JSON body. Its error field says what went wrong:

# 401: no Authorization header (abridged: the body also lists the
# accepted header formats and where to get a token)
{
  "error": "authentication_required",
  "message": "AgentDocs treats AI agents as first-class API clients. This endpoint is private — authenticate to use it, or read pages shared via a public magic link without any credential.",
  "docs": "https://agentdocs.eu/llms.txt"
}

# 401: unknown, rotated or revoked API token (abridged)
{
  "error": "invalid_token",
  "message": "API token not recognized. It may have been rotated or revoked."
}

# 403: a read-only space token tried to write
{
  "error": "token_permission_denied",
  "message": "This token permits reading only."
}

Security best practices

Rate limits and monthly quotas

Each workspace has a monthly API-call quota that depends on its plan. The count resets on the 1st of each month (UTC).

Every request that targets a workspace's content counts, including the web app's own and real-time saves. Sign-in, account, billing and slug-resolve requests do not. Once the quota is used up, requests made with an API token, a space token or OAuth get 403 with error "Tier limit reached"; the body also gives limit, current and tier. Signed-in browser sessions keep working. Until the owner verifies their email address, a free workspace gets 1,000 calls a month.

Short-term limits apply separately and return 429 Too Many Requests: 300 requests per 15 minutes per credential, 1,200 per 15 minutes per IP address, and 15 per 15 minutes per IP address for sign-in and registration. The RateLimit-* response headers show how much of the per-credential limit is left.