An API key authenticates a request to the customer-facing REST API. Each key carries its own name, scopes, and expiry, so you can tell one integration's key from another and revoke exactly the one that's misbehaving without touching the rest.
Before you start
You need permission to manage integrations. Decide what the integration actually needs to do before creating the key — you can't add a scope to an existing key later; create a new one instead.
Scopes
Pick only what the integration needs:
| Scope | Grants |
|---|---|
sboms:write | Uploading SBOMs (POST /api/v1/products/{id}/sboms) |
alerts:read | Reading alerts (GET /api/v1/alerts) |
cases:read | Reading cases (GET /api/v1/cases) |
products:read | Reading products and versions (GET /api/v1/products) |
A CI pipeline pushing SBOMs on every build typically needs only sboms:write. A
dashboard or a chat-ops bot that only reads alerts needs only alerts:read. A
request against an endpoint the key's scopes don't cover fails with 403.
Steps
- Open Settings → API.
- Name the key after what will use it — something specific enough to recognize later, like "Release pipeline" or "Jira sync," not "key 1."
- Choose an expiry: 90 days, a year, or never.
- Check the scopes the integration needs.
- Click Create key.
What you should see
The secret is shown exactly once, in full, right after creation. Copy it now — Declara stores only a SHA-256 hash from this point on, so the key can't be shown again and support can't retrieve it for you either. If it's lost before you copy it, revoke the key and create a new one.
Afterward, the key appears in your list showing its name, scopes, prefix (enough to recognize it, not enough to use it), creation date, expiry, and last-used time, along with how many calls it's made this month.
Revoking is immediate and irreversible
Revoking a key stops anything using it right away, and the secret can't be recovered afterward — a replacement has to be created and deployed. Do it deliberately, not as a first troubleshooting step.