Authentication & API keys
Create project-scoped API keys and use them to authenticate the SDK, CLI, and API.
Anything calling Compass from outside the app — the SDK, the CLI, or the HTTP API — authenticates with an API key. A key is scoped to a single project and carries its own access, so you never pass the project separately.
Creating a key
Go to Settings → Developers → API Keys and fill in:
- Name — something recognizable, like "CI Pipeline".
- Type — a service account (an independent identity) or a personal token (which inherits your own access).
- Project — the one project the key can act in.
- Expires — an optional lifetime in days; leave blank for a key that doesn't expire.
When you create the key, its secret is shown once. Copy it and store it somewhere safe — you can't retrieve it again afterward. If you lose it, revoke the key and create a new one.
Treat keys like passwords
A key grants access to its project. Keep it out of source control, prefer environment variables or a secrets manager, and give each system its own key so you can revoke one without disrupting the others.
Service accounts vs personal tokens
- A service account is its own identity, independent of any person — the right choice for automations, CI, and backend integrations that should keep working regardless of who set them up.
- A personal token acts as you, inheriting your access — handy for quick scripts and local experimentation.
Each key has a role within its project, which determines what it can do. Sensitive actions — such as creating or changing connections, which hold credentials — require an admin-scoped key. Running and reading work is available to any key for the project.
Using a key
Send the key as a bearer token on every request:
Authorization: Bearer <your-api-key>The SDK and CLI handle this for you once configured. Because the key is already scoped to a project, you don't send a project id yourself — Compass resolves it from the key.
A common pattern is to keep the key in an environment variable; the CLI reads
COMPASS_API_KEY (and COMPASS_BASE_URL) automatically:
export COMPASS_API_KEY="<your-api-key>"
export COMPASS_BASE_URL="https://your-compass-url"Revoking a key
In Settings → Developers → API Keys, each key shows its type, project, and creation date. Click Revoke to disable it immediately — any client using it stops working at once. Revocation can't be undone.