API keys
An API key lets a program talk to the CyberOptix CTEM Platform - a CI pipeline triggering a scan, a script exporting findings, an integration you build yourself.
Keys belong to the organization rather than to a person. That is deliberate: a key tied to someone's account stops working when they leave, usually during an incident and usually at the least convenient moment.
Creating one
Integrations → API Keys → Add. Give it a name describing what will use it - ci-main
beats key1, because the first question when a key needs rotating is what depends on it.
Select scopes, then create. The key is shown once. There is no way to retrieve it afterwards; a lost key is replaced, not recovered.
Scopes
| Scope | Allows |
|---|---|
assets:read | List and get hosts, web apps, cloud resources, and EDR devices |
findings:read | List, search, get, and export findings |
findings:write | Create and update findings and remediations |
vulnerabilities:read | List, search, get, and export vulnerabilities |
vulnerabilities:write | Update vulnerability status, risk acceptance, and assignee |
scans:trigger | Trigger vulnerability, DAST, and SAST scans |
soc:read | List and get alerts and incidents |
soc:write | Create and update alerts and incidents |
jira:read | List and get Jira tickets and rules |
jira:write | Create and update Jira tickets |
reports:read | List and download generated reports |
reports:write | Generate reports and create schedules |
Scopes are functional boundaries, not user roles. A key has no role and no person behind it; it can do exactly what its scopes allow and nothing else.
Grant the minimum
The common shapes:
| Use | Scopes |
|---|---|
| Pipeline: scan on build, fail on Critical | scans:trigger, vulnerabilities:read |
| Export findings to a dashboard | findings:read, vulnerabilities:read |
| Push findings into your own tracker | findings:read, jira:write |
| Scheduled reporting | reports:write, reports:read |
Note the first one needs no write access at all. A build pipeline with
vulnerabilities:write is a pipeline that can silently close findings, which is a
strange capability for a build to have.
Using a key
Send it as a bearer token against your own API hostname:
curl -H "Authorization: Bearer $API_KEY" https://<your-api-hostname>/api/v1/...
Your API hostname is specific to your deployment - take it from the platform rather than assuming a pattern, because it differs between brands.
The API reference documents every endpoint. Which ones a key can reach depends on its scopes.
Looking after keys
Store them in a secret manager. Not in a repository, not in a pipeline definition, not in an environment variable set by hand on a shared machine. A key is a credential with no second factor and no user attached - whoever holds it has its scopes.
One key per consumer. Sharing a key between two pipelines means rotating it breaks both, so it never gets rotated.
Rotate on a schedule, and whenever someone with access to it leaves. Create the replacement, move the consumer across, then revoke the old one - in that order, so nothing is broken in between.
Revoke immediately if a key is exposed. A key committed to a repository is exposed even after the commit is removed, because the history and any clone still carry it.
API
The endpoints behind this section are in the API reference.
Next
- Roles and permissions - how scopes differ from roles
- Webhooks - the inbound endpoints vendors post to