Generate and scope an API key
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
- The Growth or Partner plan. API keys are part of the integrations entitlement, so the CI upload, the release gate, the MCP server and Dependency-Track all need it. A key created before a downgrade keeps working; only creating a new one is refused.
- The owner or an admin role (
workspace.update). - A decision on what the integration needs to do. 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 | POST /api/v1/products/{id}/sboms |
alerts:read | GET /api/v1/alerts |
cases:read | GET /api/v1/cases, GET /api/v1/advisories |
products:read | GET /api/v1/products, GET /api/v1/products/{id}/vex, GET /api/v1/products/{id}/gate |
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. A pipeline
that pushes an SBOM and then gates the release needs
sboms:write and products:read.
Keys for an AI assistant
The same keys connect an assistant to the read-only
MCP server. The key needs products:read to
connect at all; alerts:read and cases:read add the alert, case, deadline and
advisory tools. Give the assistant its own key, not the pipeline's, so either can be
revoked alone. No scope lets an assistant change anything.
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.