Skip to main content
API keys let your team interact with Odin programmatically — querying findings, assets, and pentests from scripts, CI pipelines, and AI agents that cannot sign in, such as Cursor, through the Odin MCP server. To connect Claude, Claude Code or VS Code, sign in from Workspace > AI agents instead; no key is needed. Open the API Keys page from Workspace > API Keys in the sidebar. Members, Admins and Owners see this item. Read only users do not.
Members, Admins and Owners can create API keys. Members see and revoke only their own keys. Admins and Owners see every key in the organisation, with who created it, and can revoke any of them. Each key belongs to exactly one organisation.
Each person can have up to 10 active API keys in an organisation, whatever their role. Revoked keys do not count. When you reach the limit, the create dialog says so; revoke a key you no longer use to create another.

​
Who a key acts as

A key acts as the person who created it. Odin checks that person’s current role on every request:
  • The key never does more than its creator’s role allows, whatever its own permissions. For example, a Member’s key cannot do anything that needs an Admin.
  • If the creator is removed from the organisation, or single sign-on or directory sync deprovisions them, all their keys in that organisation are revoked. Inviting or provisioning them again does not bring the old keys back; they create new ones.
  • If the creator becomes Read only, their keys stop working straight away but are kept. Requests return 403 with code API_KEY_CREATOR_READ_ONLY, and Admins and Owners see the key marked Inactive on the API Keys page. If the creator’s Member role is restored, the key works again.
  • Changes made with a key, such as status updates, assignments, discussion messages and pull request links, are recorded against the creator’s name.

​
Creating an API key

1

Open the API Keys page

Go to Workspace > API Keys in the sidebar.
2

Click Create API Key

The creation dialog opens with Read & Write selected for the remediation workflow. You can change it to Read only before creating the key.
3

Name the key

Give the key a descriptive name (for example, Cursor MCP, CI Findings Sync, or Dashboard Export). The name is visible only to your team.
4

Choose permissions

Use Read only when an agent should inspect data. Use Read & Write when it should update finding statuses or link an existing GitHub pull request after you explicitly ask it to.
5

Copy the key

The full key is shown once and never displayed again. Copy it now and store it somewhere safe.
The raw API key is shown only once. If you lose it, revoke the key and create a new one. Treat keys like passwords and never commit them to source control.

​
Permissions

A Read & Write key contains both read and write permissions. Server-side permission checks remain in force; choosing the default does not change existing keys or silently upgrade a Read-only key. For the remediation loop, ask the agent before every mutation. A matching identifier or pull-request URL is not permission to change Odin data. Odin never creates commits, pushes branches, or creates pull requests.

​
Organisation scoping

A key is permanently scoped to the organisation that created it. Odin resolves human finding references such as ODI-12 only within that organisation and returns the canonical stored identifier. Findings, integrations, GitHub installations, and retest history from another organisation are not exposed. If you belong to multiple organisations, create one key per organisation and configure a separate MCP server entry for each (for example, odin-acme and odin-internal). This also makes revocation and audit attribution clear.

​
Revoking a key

To revoke a key, open Actions on its row, choose Revoke, and confirm. Any integration using that key stops working immediately. Revocation cannot be undone. Members can revoke their own keys; Admins and Owners can revoke any key, including an inactive one whose creator is now Read only. Keys of someone who leaves the organisation are revoked for you.

​
Connecting an AI agent (MCP)

To connect Claude, Claude Code or VS Code, you do not need a key: go to Workspace > AI agents and sign in with your Odin account. See Odin MCP Server. Use an API key for Cursor, which cannot finish sign-in with Odin, and for scripts, CI and other clients that cannot sign in. After you create a key, the dialog shows the setup for Cursor, VS Code, Claude Code, Codex and a local Claude Desktop server, with the key already in each snippet. The Add to Cursor and Add to VS Code buttons never include the key. Restart the client after changing its MCP configuration.
Read-only keys remain appropriate for discovery, context, and retest reads; create a new Read & Write key for mutations.
For the full tool reference, GitHub remediation flow, and troubleshooting, see Odin MCP Server.

​
Calling the REST API directly

If you’d rather make HTTP requests yourself, every API key works against the Odin REST API. Send the key as a Bearer token in the Authorization header. Keys always start with the odin_ prefix:
Requests are scoped to the organisation the key belongs to. A Read & Write key is required for any mutating endpoint, including status changes and manual GitHub PR linking.

​
Human finding references

The finding detail endpoint accepts either an internal finding ID or a human reference such as ODI-12. The prefix is an organisation-local alias; the numeric suffix is looked up only in the organisation identified by the key. Odin returns a non-enumerating 404 for malformed, unknown, invisible, or cross-organisation references.

​
Interactive reference

Odin ships an interactive API reference at odin.borghq.io/api/docs. Sign in to the dashboard first, then open it to browse every public endpoint, see request and response shapes, and try calls from the page. The same spec is served as raw OpenAPI 3.1 at /api/openapi.json if you want to generate a client or import calls into Postman.

​
Rate limits

Each key is limited to 100 requests per minute on a sliding window. When you exceed it the API returns 429 Too Many Requests with a Retry-After header in seconds.

​
Security notes

  • Treat API keys like passwords. Never commit them to source control or share them in chat.
  • Use one named key per integration or agent so you can revoke a single key if a machine or session is compromised.
  • Keys are scoped to a single organisation. They cannot access data from other organisations.
  • Manual PR linking verifies the URL through the organisation’s GitHub App installation; Odin does not trust caller-supplied repository metadata or expose GitHub credentials.