Authentication

SigSentry has two authentication methods. Use the right one for the right context.

JWT (dashboard sessions)

JWTs are issued at login or signup. The dashboard handles them transparently — sending them on every API request and refreshing before expiry. Permissions are derived from your role.

You don't typically work with JWTs directly. The API Reference's authentication section covers API keys, which are the right credential for programmatic use.

API keys

API keys are for programmatic use: scripts, CI integrations, the @sigsentry/react SDK, custom integrations. They come in three explicit types, each minted from a different dashboard page:

The page you're on decides the type — there's no "what kind of key?" picker. Mint from Project → SDK Keys for browsers and mobile, from Project → API Keys for one-project automation, from Organization → API Keys for cross-project tooling.

Creating

You provide:

• Name — for your reference (e.g. "Production ingest", "CI smoke tests")
• Permissions — explicit list (see below). For ss_pub_* keys this is locked to the analysis-only set.

The full key is shown once at creation time. After dismissing the modal, you can never retrieve the full key again — only the prefix. Store it in a secret manager immediately.

Sending

Include the key in the Authorization header:

curl -H "Authorization: Bearer ss_secret_abc..." \
  https://api.sigsentry.com/v1/analyses

ss_secret_* and ss_pub_* keys carry their project binding implicitly — the API resolves the project from the key. For ss_org_* keys, also include the project's ID:

curl -H "Authorization: Bearer ss_org_abc..." \
     -H "X-Project-Id: <uuid>" \
  https://api.sigsentry.com/v1/analyses

The dashboard sets X-Project-Id automatically based on which project you're viewing.

Permissions

Each API key has an explicit permission list. The permissions are:

ss_pub_* keys are locked to analysis:create and analysis:read — there's no picker, and the API rejects mint requests that try to broaden the set. ss_secret_* and ss_org_* keys can carry any combination from the table above.

To mint or revoke keys, use the dashboard. Programmatic keys never carry permission to create or revoke other keys.

Revoking

On the matching dashboard page (Project → SDK Keys, Project → API Keys, or Organization → API Keys), click Revoke on any key. The key stops working immediately. There's no soft-delete — once revoked, it's revoked.

You should also rotate keys periodically (e.g. every 90 days). Best practice: create a new key, deploy it, verify usage, then revoke the old one.

Legacy keys

If you have keys with the tb_* (legacy Traceback) or ss_live_* prefix, they continue to authenticate during a 6-month sunset window. The dashboard shows a banner on each API Keys page when legacy keys are detected. Rotate at your convenience — after the window closes, legacy prefixes return 401 KEY_FORMAT_DEPRECATED.

Last-used tracking

Every API key tracks lastUsedAt so you can spot keys that aren't in use and revoke them safely.