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

# API keys

> Create scoped workspace keys with one-time delivery, rotation grace, and CIDR controls.

<Frame caption="The API keys screen. A new key is shown once, at creation time.">
  <img src="https://mintcdn.com/auto-gtm/iXt5uMxsbIiTmJfR/images/console-api-keys.png?fit=max&auto=format&n=iXt5uMxsbIiTmJfR&q=85&s=a562d6ec5c742793077c54ac8283d042" alt="The API keys screen. A new key is shown once, at creation time." width="2880" height="1800" data-path="images/console-api-keys.png" />
</Frame>

Machine keys begin with <code>gp\_live\_</code> and belong to one workspace. They authenticate API routes only through an exact bearer header:

```http theme={null}
Authorization: Bearer gp_live_...
```

## Scope catalog

| Scope                         | Route capability                                |
| ----------------------------- | ----------------------------------------------- |
| <code>workspace:read</code>   | Workspace summary and team reads                |
| <code>settings:read</code>    | Profile, settings, model, and competitor reads  |
| <code>settings:write</code>   | Profile, settings, model, and competitor writes |
| <code>connections:read</code> | Connection and credential-status reads          |
| <code>connections:test</code> | Connection tests                                |
| <code>prompts:read</code>     | Prompt reads                                    |
| <code>prompts:write</code>    | Prompt mutations and regeneration               |
| <code>runs:read</code>        | Run and research reads                          |
| <code>runs:write</code>       | Run, research, SEO, and page-evaluation jobs    |
| <code>recs:read</code>        | Recommendation reads                            |
| <code>recs:write</code>       | Recommendation generation and transitions       |
| <code>reports:read</code>     | Reports and page-evaluation reads               |
| <code>metrics:read</code>     | Score, time-series, metrics, and SEO reads      |
| <code>chat:read</code>        | Thread reads                                    |
| <code>chat:write</code>       | Chat and thread writes                          |
| <code>credits:read</code>     | Balance and usage reads                         |

Create the narrowest key that supports the client.

## One-time delivery

<Steps>
  <Step title="Create">
    An authorized browser session requests the key name, scopes, and optional CIDR list.
  </Step>

  <Step title="Receive once">
    The secret is encrypted for delivery and shown through a session-bound handle. The delivery window is 10 minutes.
  </Step>

  <Step title="Store it">
    Copy the secret into the client's secret store. During delivery, the server keeps an encrypted session-bound payload and an HMAC-SHA-256 verifier.
  </Step>

  <Step title="Acknowledge">
    Acknowledgement activates the key and clears the encrypted delivery payload. The HMAC verifier remains for authentication.
  </Step>
</Steps>

The same session can resume an unexpired pending delivery. The key cannot be recovered after acknowledgement or expiry.

## Rotation

Rotation creates a pending replacement with the same scopes and CIDR policy. The old key stays active until the new secret is acknowledged. At acknowledgement:

* The replacement becomes active.
* The old key enters a 15-minute grace state.
* Confirming rotation revokes the old key early.
* Otherwise authentication lazily revokes it when grace expires.

Revocation is idempotent.

## CIDR restrictions

Keys can contain strict IPv4 or IPv6 CIDR ranges. The direct peer address is authoritative unless:

1. <code>GEO\_TRUST\_PROXY=1</code>, and
2. the direct proxy peer is loopback.

Only then can the application use the forwarded client address. Forwarding headers from an untrusted peer are ignored. A missing or nonmatching effective address returns HTTP 403.

## States

| State   | Can authenticate         |
| ------- | ------------------------ |
| Pending | No                       |
| Active  | Yes                      |
| Grace   | Yes, until grace expires |
| Revoked | No                       |

## Session-only management

API key creation, delivery, acknowledgement, rotation, confirmation, and revocation require a browser session. An API key cannot mint or rotate other keys.

<Warning>
  A key is a workspace credential, not a user credential. Removing a team member does not automatically revoke keys they may have copied.
</Warning>