Context Repo DocsAuthentication
Authenticate API requests using a Bearer JWT token from Clerk or an API key from your Context Repo dashboard.
Every API request requires an Authorization header. Context Repo supports two authentication methods: Bearer JWT for session-based access and API-Key for programmatic integrations.
Bearer JWT
Use a Clerk-issued JWT token when making requests on behalf of a signed-in user. This is the same token your browser uses when you're logged into the dashboard.
Header format:
Authorization: Bearer <clerk_jwt_token>The token must meet these requirements:
- Issued by Clerk for your Context Repo account
- The JWT audience must be set to
convex - The token must not be expired
Bearer tokens have full access to all resources owned by the authenticated user — they aren't restricted by permission scopes.
Bearer JWT authentication is primarily used by the dashboard and internal integrations. For most external tools and scripts, API key authentication is simpler to set up.
API Key
API keys provide scoped, long-lived access for external tools, scripts, and integrations like the Chrome Extension and MCP clients.
Header format:
Authorization: API-Key <your_api_key>Getting an API Key
- Open the Context Repo dashboard
- Go to Settings > API Keys
- Click New API Key
- Give it a name and select the permission scopes you need
- Click Create and copy the key immediately — it's only shown once
For a detailed walkthrough of key creation, viewing, and revoking, see the Settings page.
Permission Scopes
API keys are limited to the scopes you assign when creating them. Two scopes are available:
| Scope | Label | What It Allows |
|---|---|---|
prompts.read | Prompts API access | Full access to prompts — list, create, update, delete, restore versions, and search through the REST API |
documents.read | Documents & Collections API access | Full access to documents and collections — create, read, update, delete, restore versions, scrape URLs, manage collection items, and deep search |
If your API key doesn't have the required scope for an endpoint, the API returns a 403 Forbidden error. Make sure you've assigned the right scopes for your use case.
Scope Requirements by Endpoint
| Endpoint Group | Required Scope |
|---|---|
Prompts (/v1/prompts/*) | prompts.read |
Documents (/v1/documents/*) | documents.read |
Collections (/v1/collections/*) | documents.read |
Search (/v1/search) | At least one of prompts.read or documents.read |
Progressive Disclosure (/v1/pd/*) | documents.read |
Document Scraping (/v1/documents/scrape) | documents.read |
MCP Capabilities (/v1/mcp/capabilities) | None (public) |
Choosing an Auth Method
| Use Case | Recommended Method |
|---|---|
| Browser-based integrations | Bearer JWT |
| Chrome Extension | API Key with documents.read |
| MCP clients (Cursor, Claude Desktop, etc.) | API Key with both scopes |
| CI/CD pipelines and scripts | API Key with the minimum scopes needed |
| Custom applications | API Key for server-to-server, Bearer JWT for user-facing |
Error Responses
Authentication failures return one of two status codes:
| Status | Meaning |
|---|---|
401 Unauthorized | Missing or invalid Authorization header — the token or key couldn't be verified |
403 Forbidden | Valid authentication, but the API key doesn't have the required permission scope |
{
"error": {
"code": 401,
"message": "Invalid authentication"
}
}