Context Repo DocsAuthentication
Authenticate API requests using a Bearer JWT session token 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 session 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 <session_jwt_token>The token must be a valid, non-expired session token issued by your signed-in dashboard session. Browser-based integrations built on top of Context Repo retrieve this token from their existing authenticated session — refer to your auth provider's documentation for the exact retrieval call.
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 for browser-based, signed-in usage. For scripts, CLI tools, MCP clients, and server-to-server integrations, use an API key — it's simpler to set up and longer-lived.
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>The header name API-Key is case-sensitive. API keys generated by the dashboard have the shape gm_<publicId>_<secret> — for example:
Authorization: API-Key gm_aB3cD4eF5gH6_xK9mN2pQ7rS5tU8vW1yZ3aB6cD9eF2gH5jK7Getting 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 scoped per resource and per access kind. Four scopes are available:
| Scope | Label | What It Allows |
|---|---|---|
prompts.read | Prompts — Read | List, read, search, and inspect prompt versions |
prompts.write | Prompts — Write | Create, update, delete, and restore prompt versions. Implies prompts.read. |
documents.read | Documents & Collections — Read | List, read, deep-search, and export documents and collections |
documents.write | Documents & Collections — Write | Create, update, delete, restore versions, scrape URLs, and manage collection memberships. Implies documents.read. |
When you create a key in the dashboard, you pick None / Read / Write per resource — there is one selector for Prompts and another for Documents & Collections. Selecting "Write" automatically grants the matching read access, so you don't need to select both.
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
Read methods (GET) require the matching .read scope; write methods (POST/PATCH/DELETE/restore) require the matching .write scope (which already includes .read).
| Endpoint Group | Read methods | Write methods |
|---|---|---|
Prompts (/v1/prompts/*) | prompts.read | prompts.write |
Documents (/v1/documents/*) | documents.read | documents.write |
Document scraping (POST /v1/documents/scrape) | — | documents.write |
Collections (/v1/collections/*) | documents.read | documents.write |
Search (GET /v1/search) | At least one of prompts.read or documents.read | — |
Progressive Disclosure (/v1/pd/*) | documents.read | — |
User profile (GET /v1/user/me) | Any authenticated request | — |
MCP Capabilities (GET /v1/mcp/capabilities) | None — public, unauthenticated | — |
Choosing an Auth Method
| Use Case | Recommended Method |
|---|---|
| Browser-based integrations | Bearer JWT |
| Chrome Extension | API Key with documents.write (needed to save scraped pages) |
| MCP clients (Cursor, Claude Desktop, etc.) | API Key with the scopes matching the MCP tools you'll use — for full read + write access, grant prompts.write and documents.write |
| 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"
}
}