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

# API keys & scopes

> Mint a workspace API key, pick the right scopes, rotate and revoke.

Programmatic access to Enoki — the MCP server and the REST API — authenticates
with a **workspace API key**, passed as a Bearer token. Keys are prefixed `egk_`,
scoped to a single workspace, and shown in full only once at creation.

## Mint a key

Only **workspace admins** can create keys.

<Steps>
  <Step title="Open API key settings">
    Sign in at [app.enokilabs.ai](https://app.enokilabs.ai) and go to
    **Settings → API Keys**.
  </Step>

  <Step title="Create a key">
    Click **Create**, give it a name, and select the scopes it needs (see below).
    The default selection is `read` + `write`.
  </Step>

  <Step title="Copy it once">
    The full key (`egk_…`) is shown **once**. Copy it and store it securely — you
    can't retrieve it again, only rotate or revoke it. The dashboard afterwards
    shows just the `egk_XXXX` prefix for identification.
  </Step>
</Steps>

## Scopes

A key carries one or more scopes. Grant the narrowest set that does the job.

| Scope                                  | Grants                                                             |
| -------------------------------------- | ------------------------------------------------------------------ |
| `read`                                 | List and read — targets, findings, run status, and the setup guide |
| `write`                                | Create targets, close findings                                     |
| `test:run`                             | Trigger assessments, validate fixes                                |
| `monitoring:read` / `monitoring:write` | Runtime monitoring SDK ingest — separate from the MCP/REST surface |
| `admin`                                | Everything — transitively implies `read`, `write`, and `test:run`  |

Scopes are hierarchical: `admin` implies `read` + `write` + `test:run`; `write`
implies `monitoring:write`; `read` implies `monitoring:read`. Crucially, **`write`
does not imply `read`** — they are independent.

## Which scope each MCP tool needs

| Scope      | MCP tools                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| `read`     | `get_setup_guide`, `list_targets`, `list_findings`, `get_finding`, `get_assessment_status`, `list_runs` |
| `write`    | `create_target`, `close_finding`                                                                        |
| `test:run` | `trigger_assessment`, `validate_fix`                                                                    |

<Warning>
  Because `write` does not imply `read`, a key that can only *create* targets
  can't *list* them or read the setup guide. For the full MCP setup flow, mint a
  key with **`read` + `write`**, and add **`test:run`** if your agent should
  trigger assessments. Don't use an `admin` (all-scopes) key for day-to-day agent
  use.
</Warning>

## Rotate and revoke

<Steps>
  <Step title="Rotate">
    Rotating issues a new key and keeps the old one valid for a **grace period**
    (default 24 hours) so you can swap it in without downtime, then the old key
    stops working. The new key is shown once, same as creation.
  </Step>

  <Step title="Revoke">
    Revoking disables a key immediately. Use it when a key is no longer needed or
    may be exposed.
  </Step>
</Steps>

## Key hygiene

* **Least privilege.** Grant only the scopes needed — never default to `admin`.
* **Keys live in config files.** MCP clients store the key in a config file on
  disk (see [Connect your agent](/connect-your-agent)), so treat it like any
  other secret and prefer a scoped, rotatable key.
* **One key per use.** Separate keys for separate consumers (a developer's Claude
  Code vs a CI pipeline) so you can rotate or revoke one without disrupting the
  other.