Create and manage API keys

An API key lets a script, CI pipeline, scanner or AI assistant call Ostorlab for your organisation without a user login. Create one in the web application under Integrations/API → API Keys.

Before you start

You need the Admin role in the organisation. Only admins can create, change or revoke API keys. You create a key while signed in to the web application. An API key cannot create another key.

A key belongs to the organisation where you create it. It acts with the role you give it and never more.

Steps

Sign in to report.ostorlab.co as an organisation admin.
Click the menu button.
Click Integrations/API to expand it, then click API Keys. You can also open https://report.ostorlab.co/integrations/api.
Click New API Key.
In the Create New API Key dialog, enter the API Key Name, up to 50 characters. Use the name of the tool that will hold the key, for example "GitHub Actions".
Select the Role. See Choose a role.
Optional: set an Expiry Date. See Expiry.
Optional: select Assign Owners. This field is not available for an Admin key. See Choose a role.
Click Create Key, then copy the API key.

Ostorlab stores only a hash of the key, so it cannot show the key again. Store the key in your secret manager right away. If you lose it, create a new key.

Choose a role

The role sets what the key can do. Pick the lowest role that covers the job.

Role	The key can	The key cannot
Admin (`admin`)	Do everything a User key does. Manage API keys, users, single sign-on, organisation settings, integrations, scanners and the audit log.	Nothing is restricted inside the organisation.
User (`user`)	Read and write. Start, re-run and stop scans. Triage vulnerabilities. Create and edit tickets, comments and test credentials. Read and audit attack-surface assets.	Do any admin task.
Reader (`reader`)	Read scans, vulnerabilities, tickets, comments and checklists. List attack-surface assets and tags.	Change anything.
Attack Surface Auditor (`attack_surface_auditor`)	List, accept, reject and edit attack-surface assets and tags.	See scans, vulnerabilities or tickets.

Choose by job:

CI scan. Starting a scan, passing test credentials and reading the result need the write and read actions. The User role has both, so a CI key does not need Admin.
AI assistant over MCP. Use Reader for questions about scans, findings and tickets. Use User if the assistant starts scans, triages findings or edits tickets. See Permissions for the action each tool needs.
On-prem scanner. Use Admin, as the on-prem scanner page states.

If your organisation uses object-level access, a key that is not Admin sees only the scans, tickets and owners granted to it. Use Assign Owners to grant them. See Owner-Based RBAC.

Expiry

The expiry date is optional. If you leave it empty, the key has no expiry date. What an expired key does depends on the path it uses.

Path	An expired key
GraphQL API	Is rejected. The platform source checks the expiry date before it runs the request. This is not yet confirmed on the production deployment.
`ostorlab` command line and CI	Is rejected. These tools call the GraphQL API, so this carries the same production caveat as the GraphQL row.
MCP server	Keeps working until you revoke it. The MCP endpoint checks the key and its revoked state, not the expiry date.

Revoking a key disables it on every path. Do not rely on an expiry date alone to retire a key. Revoke it.

Use the key

Pass the key to Ostorlab the way each tool expects.

Where	How the key is passed
GraphQL API	The `X-Api-Key` header, on requests to `https://api.ostorlab.co/apis/graphql_token/`.
MCP server	In the URL path: `https://api.ostorlab.co/apis/mcp/XXXX.XXXXXXX/`. The trailing slash is required.
`ostorlab` command line	The `--api-key` option.
On-prem scanner	`ostorlab --api-key=XXXX.XXXXXXX scanner --scanner-id=XXXX-XXXX-XXXXX`

X-Api-Key: XXXX.XXXXXXX

export OSTORLAB_API_KEY="XXXX.XXXXXXX"
ostorlab --api-key="$OSTORLAB_API_KEY" ci-scan run --title="Nightly scan" --scan-profile=fast_scan android-apk app.apk

In a CI system, store the key as a secret. The integration pages use these names:

CI system	Name used in the docs
GitHub Actions	Secret `ostorlab_api_key`, passed to the action input `ostorlab_api_key`.
GitLab CI	Variable `OSTORLAB_API_KEY`.
Bitbucket Pipelines	`OSTORLAB_API_KEY`, exported from the variable `SECRET_OSTORLAB_API_KEY`.
Jenkins	A Secret text credential with the ID `apiKey`.
Bitrise	Secret `API_KEY`.
GoCD	Secure Variable `OSTORLAB_API_KEY`.
TeamCity	Environment variable `OSTORLAB_API_KEY`.
Harness	Secret `OSTORLAB_API_KEY`.

In CircleCI and Azure DevOps, you enter the key in the Ostorlab orb or extension step of the pipeline.

Revoke or replace a key

Revoke a key when you retire a tool, when someone who knew the key leaves, or when the key leaks. A revoked key stops working at once, and you cannot undo it.

To revoke a key, use the trash icon in the Actions column of the key list, the revoke_api_key MCP tool or the revokeApiKey GraphQL mutation. All three need admin access. Through MCP, a key cannot revoke itself.

To replace a key without downtime:

Create a new key with the same role.
Update the secret in the tool that uses it.
Check that the tool works with the new key.
Revoke the old key.

To rename a key or change its role, expiry date or owners, use the pencil icon in the Actions column. The update_api_key MCP tool is stricter: it can lower a role, drop owners, bring an expiry date forward and rename a key. It cannot raise a role or move an expiry date later.

Keep it safe

Treat a key like a password. Store it as a masked secret in your CI system.
Never commit a key to a repository, a log or a ticket.
Treat the MCP endpoint URL like the key itself. The URL contains the key.
Use one key per tool. You can then revoke one key without breaking the others.
To name a key in a message, use its masked form: the prefix followed by asterisks.