Key permissions
The permission list each API key carries, what each one allows, and how to grant the minimum a job needs
Every API key carries an explicit list of permissions chosen at creation time. The key can only do what its permission list allows — nothing more, nothing less.
The permission list
| Permission | What it allows | Example endpoints |
|---|---|---|
analysis:create | Trigger new analyses, ask follow-up questions, submit feedback | POST /v1/analyses, POST /v1/analyses/:id/followup |
analysis:read | View existing analyses and their results | GET /v1/analyses, GET /v1/analyses/:id |
config:read | View project configuration — log sources, channels, watchdog rules, team | GET /v1/log-sources, GET /v1/channels, GET /v1/watchdog/rules |
config:write | Modify project configuration — add log sources, edit rules, manage channels | POST /v1/log-sources, PATCH /v1/watchdog/rules/:id |
To mint or revoke keys, use the dashboard — Project → SDK Keys,
Project → API Keys, or Organization → API Keys. There is no
apikey:* permission, so a programmatic key never carries the right
to mint another key on your behalf.
Locked permissions on ss_pub_*
Public keys (ss_pub_*) are locked at the platform level to
analysis:create and analysis:read. The dashboard form has no
permission picker, and the API rejects mint requests that try to
broaden the set with 400 INVALID_PUBLIC_KEY_PERMISSIONS. This makes
SDK keys safe to ship in browsers and mobile apps — even a stolen key
can only run and read analyses.
ss_secret_* and ss_org_* keys can carry any combination from the
table above, picked at creation time.
How keys differ from roles
Dashboard users have a role (owner, admin, member, viewer) that maps to a fixed set of permissions. API keys do not.
A key created by an admin doesn't automatically inherit the admin's permissions. The creator picks the key's permission list explicitly. A key only ever has what was granted at creation time.
That separation is intentional — it lets you hand a narrow, purpose- built credential to a CI job or third-party integration without worrying that someone's role change will quietly expand what the key can do.
| Role-based access (dashboard users) | API key access | |
|---|---|---|
| Permissions source | Derived from the user's role | Listed explicitly on the key |
| Changes when role changes | Yes | No — by design, you rotate a key when its needs change |
| Typical scope | All projects the user belongs to | One project, or all projects |
| Lifetime | While the user is logged in | Until revoked |
Granting the minimum
The most common mistake is over-granting. A CI job that runs analyses
on every pull request needs analysis:create and analysis:read —
nothing more. Don't tick config:write "just in case."
CI / smoke tests
analysis:create + analysis:read. Triggers analyses, reads results, no configuration access.
Read-only dashboard widget
analysis:read + config:read. Lists analyses and shows project configuration; can't modify anything.
Infra-as-code provisioner
config:read + config:write on an ss_org_* key (it spans projects). Creates and updates log sources and rules from Terraform or similar; no analysis access needed.
Full server integration
All four base permissions on an ss_secret_* or ss_org_* key. Use sparingly — usually only for trusted internal tools.
A pattern: minimum-permission keys for CI
A typical CI pipeline triggers an analysis on each deploy and waits for the result:
# Stored as SIGSENTRY_CI_KEY in GitHub Actions secrets.
# Permissions: analysis:create, analysis:read
curl -X POST https://api.sigsentry.com/v1/analyses \
-H "Authorization: Bearer $SIGSENTRY_CI_KEY" \
-H "X-Project-Id: $SIGSENTRY_PROJECT_ID" \
-d '{ "description": "post-deploy smoke check", "windowMinutes": 15 }'That key cannot read your team list, edit log sources, or change notification channels — even if a maintainer's account is later compromised, the CI key's reach is bounded.
Checking what a key can do
The dashboard's API Keys table shows the permission list for every key in the Permissions column. To audit a key:
Find the key by name or prefix
Each row shows the key's prefix — match it against the prefix your application is using.
Read the Permissions column
It lists every permission the key carries. If the list is broader than the integration needs, revoke the key and create a new one with fewer permissions.
To change what a key can do, rotate it. Create a new key with the desired permission list, switch the integration over, and revoke the old one. See Revoking keys for the rotation procedure.