API and integration keys
API keys let your systems talk to CRAnotify — today mainly to push bills of materials from your pipelines. They are managed from Account area › API and are an administrator action.
Creating a key
- Give it a name that says what it is for («CI build backend», «Dependency-Track production»), not «key 1».
- Select the scopes: only those needed.
- On creation the full secret is shown once. Copy it straight into your system's secret store.
The secret cannot be recovered: the system keeps only its digest. If you lose it, rotate the key — it takes seconds, and nobody should be keeping a secret in the clear «just in case».
Scopes
| Scope | Allows |
|---|---|
incidents:write | Register an inbound security signal. |
products:read | Read the product catalogue with SBOM status and risk level. |
compliance:read | Read the organisation's compliance score. |
products:write | Push bills of materials from pipelines. |
Pick only the scopes you need: there are no all-purpose keys. A key used outside its scopes gets an explicit refusal with 403. The full list of endpoints each scope unlocks is in the API v1 reference.
Authenticating a call
X-CRA-API-Key: cra_live_…
# or
Authorization: Bearer cra_live_…A complete SBOM push for an SKU (see Bill of materials and SBOM tools):
curl -X POST https://api.cranotify.eu/api/v1/external/products/SKU-123/sbom \
-H "X-CRA-API-Key: cra_live_…" \
-H "Content-Type: application/json" \
--data-binary @sbom.json| Code | Meaning |
|---|---|
401 | Key missing, wrong, revoked or expired. |
403 | The key is valid but lacks the required scope. |
422 | Content not recognised (invalid SBOM format). |
405 | Method not allowed: intake accepts POST only. |
429 | Rate limit exceeded (100/min per key). |
Rotation and revocation
Creation, rotation and revocation leave a row in the activity registry, with the key's name (never the secret).
Good practice. One key per system, never one shared across integrations: only then does revocation hit what it should and nothing else. Rotate whenever someone with access to the secrets leaves.
The public API host
The public API answers at api.<domain>. It exposes four endpoints: opening an inbound signal, reading the product catalogue, reading the compliance score and SBOM ingest. The three reads/intake also answer in the short form under /v1. Every endpoint, with parameters, schemas and examples, is in the API v1 reference; the raw OpenAPI 3 document is at https://api.cranotify.eu/swagger/openapi.json and the navigable console at https://api.cranotify.eu/swagger.
GET https://api.cranotify.eu/v1/products
{"products":[ … ],"count":N}Alternatives to the API
Many integrations need no keys at all:
- Receiving events in your systems: the signed webhook.
- Extracting the registry: the CSV export, which includes the integrity chain digests.
- Extracting products: the CSV export of the register, with its matching import.
- Exporting account data: the JSON export from Account area › Legal.