> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borghq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Programmatic access to Odin and the Odin MCP server

API keys let your team interact with Odin programmatically — querying findings, assets, and pentests from scripts, CI pipelines, and AI agents like Cursor or Claude through the Odin MCP server.

Open the API Keys page from **Management > API Keys** in the sidebar.

<Info>
  Only **Admin** and **Owner** roles can create or revoke API keys. Other members can't see this page.
</Info>

## Creating an API key

<Steps>
  <Step title="Open the API Keys page">
    Go to **Management > API Keys** in the sidebar.
  </Step>

  <Step title="Click Create API Key">
    The creation dialog opens.
  </Step>

  <Step title="Name the key">
    Give the key a descriptive name (e.g. `Cursor MCP`, `CI Findings Sync`, `Dashboard Export`). The name is visible only to your team.
  </Step>

  <Step title="Choose permissions">
    Pick **Read only** for query-only access, or **Read & Write** to also allow mutations.
  </Step>

  <Step title="Copy the key">
    The full key is shown once and never displayed again. Copy it now and store it somewhere safe.
  </Step>
</Steps>

<Warning>
  The raw API key is shown only once at creation time. If you lose it, revoke the key and create a new one.
</Warning>

## Permissions

| Permission       | Scope                                                                  |
| ---------------- | ---------------------------------------------------------------------- |
| **Read only**    | Read access to findings, assets, pentests, reports, and integrations   |
| **Read & Write** | Same as read, plus mutation access (status changes, asset edits, etc.) |

For most automation and AI-agent use cases, **Read only** is sufficient and recommended.

## Revoking a key

To revoke a key, click the revoke action next to it in the table and confirm. Any integration using that key will stop working immediately. Revocation cannot be undone.

## Connecting an AI agent (MCP)

The [Odin MCP server](https://www.npmjs.com/package/@borgresearch/odin-mcp) lets AI agents query your organisation's data through the Model Context Protocol. Once connected, you can ask agents like Cursor, Claude, or Codex questions like "What are my critical findings?" or "List recently discovered assets" and get live answers.

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 your API key supplied as the `ODIN_API_KEY` environment variable.

<Tip>
  After creating a key, the setup guide in the create dialog pre-fills the key into each snippet so you can paste it directly into your agent config.
</Tip>

For Windsurf, VS Code, Cline, and other MCP clients, see the [Odin MCP package on npm](https://www.npmjs.com/package/@borgresearch/odin-mcp) for client-specific configuration.

## Calling the REST API directly

If you'd rather make HTTP requests yourself instead of going through MCP, 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:

```bash theme={null}
curl https://odin.borghq.io/api/findings \
  -H "Authorization: Bearer odin_your_key_here"
```

Requests are scoped to the organisation the key belongs to, and a **Read & Write** key is required for any mutating endpoint (status changes, asset edits, and so on).

### Interactive reference

Odin ships an interactive API reference at [odin.borghq.io/api/docs](https://odin.borghq.io/api/docs). Sign in to the dashboard first, then open it to browse every public endpoint, see the 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 it 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) telling you how long to wait before retrying.

## 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 can't access data from other organisations a key holder belongs to.