API Authentication

How to authenticate with the AgentDocs API: JWT sessions, API tokens, or OAuth for MCP connectors.

Overview

AgentDocs supports three authentication methods. Which one you use depends on your use case:

JWT Authentication

JWT authentication is a two-step process: first you log in to get an access token, then you include that token in subsequent requests.

Step 1: Log In

Send your credentials to the login endpoint to receive a JWT access token:

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

# Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "usr_abc123",
    "name": "Alice",
    "email": "alice@example.com"
  }
}

Step 2: Use the Token

Include the JWT token 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, scripts, and any non-interactive use. They are long-lived, don't expire, and use a simple header format.

Getting Your API Token

Your API token is displayed on the dashboard after you log in. You can also find it in your account settings. To retrieve it:

1. Log in to AgentDocs at https://agentdocs.eu/login
2. Navigate to your Dashboard
3. Your API token is shown in the top section of the dashboard page
4. Click the copy button to copy it to your clipboard

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"}'

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 Token Access (No Auth)

For read-only access to individual pages, share links provide a third option that requires no authentication at all. The share token embedded in the URL serves as the credential:

# No Authorization header needed!
curl https://agentdocs.eu/api/shared/abc123def456/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

When authentication fails, the API returns standard HTTP error codes:

# Example error response (401)
{
  "error": "Authentication required"
}

# Example error response (403)
{
  "error": "Insufficient permissions"
}

Security Best Practices

API Rate Limits

API calls are metered per workspace per month. The limits depend on your plan:

Usage is tracked per workspace. You can monitor your current usage in the workspace settings under the Billing tab.