Skip to main content

Authentication

The Raven Docs API uses API keys for authentication.

Creating an API Key​

  1. Go to Settings → API Keys
  2. Click Create API Key
  3. Give it a name (e.g., "CI/CD Integration")
  4. Copy the key immediately (it won't be shown again)
caution

API keys have full access to your workspace. Treat them like passwords.

Using API Keys​

Include your API key in the Authorization header:

curl http://localhost:3000/api/workspaces \
  -H "Authorization: Bearer raven_sk_abc123..."

TypeScript SDK​

import { RavenDocs } from '@raven-docs/sdk';

const client = new RavenDocs({
  apiKey: process.env.RAVEN_API_KEY,
});

Environment Variables​

Store your API key in environment variables:

# .env
RAVEN_API_KEY=raven_sk_abc123...

Never commit API keys to version control.

API Key Permissions​

API keys inherit permissions from the user who created them:

User RoleAPI Key Access
AdminFull workspace access
EditorCreate/edit content only
ViewerRead-only access

Scoped Keys (Coming Soon)​

Limit API keys to specific operations:

{
  "name": "Read-only Integration",
  "scopes": ["pages:read", "tasks:read"]
}

MCP Authentication​

The MCP server uses the same API keys:

{
  "mcpServers": {
    "raven-docs": {
      "url": "http://localhost:3000/api/mcp-standard",
      "headers": {
        "Authorization": "Bearer raven_sk_abc123..."
      }
    }
  }
}

See MCP Authentication for details.

OAuth Configuration​

You can configure OAuth 2.0 providers (Google, GitHub) for your self-hosted instance.

Supported Providers​

  • Google OAuth
  • GitHub OAuth
  • SAML (for enterprise SSO)

See Configuration for setup details.

Security Best Practices​

Do​

  • Store keys in environment variables
  • Use different keys for different environments
  • Rotate keys periodically
  • Use scoped keys when available
  • Monitor API usage for anomalies

Don't​

  • Commit keys to git
  • Share keys between team members
  • Use production keys in development
  • Expose keys in client-side code
  • Log full API keys

Revoking Keys​

To revoke an API key:

  1. Go to Settings → API Keys
  2. Find the key to revoke
  3. Click Revoke
  4. Confirm deletion

Revoked keys immediately stop working.

Troubleshooting​

401 Unauthorized​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Solutions:

  • Verify the key is correct
  • Check for extra whitespace
  • Ensure the key hasn't been revoked
  • Confirm the user still has access

403 Forbidden​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

Solutions:

  • Use a key from a user with appropriate permissions
  • Check if the resource exists and is accessible
  • Verify workspace membership