Authentication
The Sophic API uses workspace-scoped API keys for authentication. These keys are used by the REST API and the MCP server.
Generate an API key
- Open Settings > API in your Sophic dashboard
- Click Create API key
- Copy the key — it is only shown once
API keys are hashed (SHA-256) before storage. Sophic never stores the raw key.
Usage
Include the key as a Bearer token in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://app.sophichq.co/api/v1/documents
Scope
Each API key is tied to a single workspace. It can only access documents within that workspace. There are no per-key permission scopes — all API keys have read access to the workspace's documents and search.
Personal Access Tokens
The CLI uses a separate authentication mechanism: Personal Access Tokens (PATs). These are user-scoped (not workspace-scoped) and are generated automatically during the sophic login flow.
PATs authenticate CLI requests via the same Authorization: Bearer header, with the workspace specified in an x-sophic-workspace header.
For automation and CI/CD, you can set environment variables instead of running the login flow:
export SOPHIC_PAT=your_personal_access_token
export SOPHIC_WORKSPACE=your-workspace-slug
export SOPHIC_API_URL=https://app.sophichq.co
API keys vs. PATs
| API Key | Personal Access Token | |
|---|---|---|
| Scope | Single workspace | User (any workspace the user belongs to) |
| Created via | Dashboard (Settings > API) | sophic login browser flow |
| Used by | REST API, MCP server | CLI |
| Workspace selection | Implicit (key is workspace-bound) | Explicit (x-sophic-workspace header or SOPHIC_WORKSPACE env var) |