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 like Cursor through the Odin MCP server. Open the API Keys page from Management > API Keys in the sidebar.
Only Admin and Owner roles can create or revoke API keys. Each key belongs to exactly one organisation.

​
Creating an API key

1

Open the API Keys page

Go to Management > 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, click the revoke action next to it in the table and confirm. Any integration using that key stops working immediately. Revocation cannot be undone.

​
Connecting an AI agent (MCP)

The Odin MCP server lets coding agents query your organisation’s data through the Model Context Protocol. Once connected, you can ask an agent questions such as “Explain ODI-12 and show me the branch to create”, then make the code change and open the PR yourself. Expand the Setup guide: connect an AI agent card on the API Keys page to see ready-to-paste configuration snippets for:
  • Cursor — add to .cursor/mcp.json or via Settings > MCP
  • Claude Desktop — add to claude_desktop_config.json
  • Claude Code — register from the terminal with claude mcp add
  • Codex — add to ~/.codex/config.toml
The snippets use the standard MCP stdio transport via npx @borgresearch/odin-mcp with the key supplied as ODIN_API_KEY. Restart the client after changing its MCP configuration.
After creating a key, the setup guide in the create dialog pre-fills the key into each snippet. 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.