Compass DocsBy Mesa
Open App

🔑 Authentication & API Keys

Every API request is authenticated with a key you create from your own account. There is no separate developer signup. If you can sign in to Compass, you can generate a key.

Creating a key

  1. Sign in and open Settings.
  2. Go to the API tab.
  3. Select Generate key and give it a label, such as "production" or "data sync".
  4. Copy the key that appears.

You can hold up to ten active keys at a time. Use separate keys for separate systems so you can revoke one without disturbing the rest.

What a key looks like

A Compass key starts with ck_live_ followed by a random string:

ck_live_AbCdEf0123456789-_xyz...

In the app, the key is listed by its prefix only, like ck_live_AbCdEf…, so you can tell your keys apart without exposing the full value.

Copy it once

The full key is shown one time, in the moment you create it. Compass stores only a one-way hash of the key, never the key itself, so it cannot show it to you again and cannot recover it for you. If you lose a key, revoke it and generate a new one.

Scopes

A key is minted with both scopes the API uses: read:metadata for all data and search calls, and read:contacts for revealing a person's private channels. You do not configure scopes today; every key carries both.

Using a key

Send the key as a bearer token in the Authorization header on every request:

curl https://compass.mesa.so/api/v1/me \
  -H "Authorization: Bearer ck_live_your_key_here"

A missing, malformed, or revoked key returns 401 Unauthorized. See Errors & Status Codes.

Revoking and rotating

You can revoke a key at any time from the API tab. Revoking takes effect immediately and is permanent. The key stays listed as revoked so you keep a record of what existed, but it can no longer make calls. To rotate, generate a new key first, move your systems over, then revoke the old one.

Keeping keys safe

  • Treat a key like a password. Anyone holding it can act as your account and spend its credits.
  • Keep keys in environment variables or a secret manager, never in source control or client-side code.
  • Use one key per system, and revoke any key you believe is exposed.