Authentication
Sophic accepts two kinds of Bearer credential: workspace-scoped API keys and user-scoped Personal Access Tokens (PATs). Both are managed from Settings → Developer in the dashboard, and both are hashed (SHA-256) before storage — Sophic never stores the raw token.
Generate an API key
- Open Settings → Developer in your Sophic dashboard
- Create a new API key
- Copy the key — it is only shown once
Usage
Include the key as a Bearer token in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://app.sophic.so/api/v1/documents
Scope
Each API key is tied to a single workspace and can only access content within it. Keys also carry scopes (read, capture, admin) that gate what they can do. The read endpoints (/documents, /search, /grep) need read access; the capture endpoint (/api/ingest/cli) requires the capture scope and a user credential, so a workspace API key cannot capture — it is rejected with a 403.
Personal Access Tokens
Personal Access Tokens (PATs) are user-scoped: a single PAT can act in any workspace the user belongs to. Because writes are attributed to the token owner, the MCP capture tool requires a PAT — see MCP Overview.
PATs authenticate via the same Authorization: Bearer header, with the target workspace specified in an x-sophic-workspace: <slug> header. The effective role of a request is the lower of the user's membership role and any downscope baked into the token.
For automation and CI/CD, set the credential via environment variables:
export SOPHIC_PAT=your_personal_access_token
export SOPHIC_WORKSPACE=your-workspace-slug
export SOPHIC_API_URL=https://app.sophic.so
API keys vs. PATs
| API Key | Personal Access Token | |
|---|---|---|
| Scope | Single workspace | User (any workspace the user belongs to) |
| Created via | Settings → Developer | Settings → Developer |
| Used by | REST API, MCP read tools | REST API, MCP read tools, capture (MCP) |
| Capture / write | ✗ (rejected 403 — needs user attribution) | ✓ with capture scope |
| Workspace selection | Implicit (key is workspace-bound) | Explicit (x-sophic-workspace header or SOPHIC_WORKSPACE env var) |