Skip to content

API keys

An API key is a secret that lets a program act for your organization: a collector on a unit, a CI pipeline that uploads SBOMs, or an AI agent. A key belongs to the organization, not to a person, so it keeps working when the person who made it leaves.

Only an admin or an owner can see, create and revoke keys. A GitHub repository can also upload without a key. See Trusted publishers.

Each key has an Access level:

Access What the key can do
Read only Read units, releases, findings, VEX statements and exports. It changes nothing.
Can propose changes Also upload SBOMs and build provenance, send collector reports, record VEX statements and file proposals.

The app says: Collectors and SBOM uploads need a key that can propose changes. Give AI agents read-only keys.

A key never has more than the second level. It cannot manage members, keys or settings, cannot delete anything, and cannot decide a proposal. A person decides.

Create a separate key for each site, pipeline or integration. Then you can revoke one without touching the others.

  1. Open API keys under Organization in the app.
  2. Under Create a key, enter a Name, for example Site Zurich collectors.
  3. Choose Access: Read only or Can propose changes. The form starts with Read only.
  4. Choose Used by: AI agent or Integration. The form starts with AI agent. The choice does not change what the key may do. It labels the key in the list.
  5. Select Create key.

The app shows the key once, under Copy this key now. It will not be shown again. Select Copy and put it in your secret store straight away. If you lose it, revoke the key and create a new one.

A key looks like this. This one is made up:

exk_example_not_a_real_key
  • Store it in the secret store of your CI system or in a file only root can read. See Upload SBOMs from other CI and the collector settings.
  • Give it to a program as an environment variable. Do not put it on a command line, because other users of the machine can see command lines, and shell history keeps them.
  • Do not write it into a repository, a chat or a ticket.
  • Use the lowest access that works. Give an AI agent a read-only key. Connect an AI assistant shows how to set one up.
  • Check Last used in the list now and then. A key that shows Never, or has not been used for months, is a candidate for revoking.

The list shows each key’s Name, Access, Used by, Last used, Agent calls (7 days) and Created, with who created it. A key that was loaded from a key file at setup shows from key file instead of a person.

Keys made before keys had access levels carry the badge Created before roles. Such a key can propose changes. The app says: This key was created before keys had roles, so it can propose changes. If an AI agent uses it, replace it with a read-only key.

To replace it, create a new key with the access you want, give it to the program, check that it works, and revoke the old one.

Select Revoke next to the key and confirm. The app asks Revoke “…”? Collectors using it stop reporting immediately. The key stops working at once. Anything that still uses it gets the answer 401.

Revoke a key when:

  • it was shown or copied somewhere it should not be;
  • the person who set it up left the team and you are not sure where it is stored;
  • the pipeline or unit it was for is gone.

Revoking a key does not delete what it uploaded.