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

# API key security

> How to create, limit, rotate, and protect Acrity public API keys.

API keys allow automations to call the Acrity public API without using a human Console session. They are managed in `Console > API Keys`, which requires a Workspace admin (platform admins also have access).

## Authentication

Send the API key in the `X-Acrity-Key` header:

```bash theme={null}
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/context"
```

<Warning>
  Do not send API keys in query strings, logs, screenshots, or support tickets. Use headers and a secrets vault.
</Warning>

## Storage

The complete key is displayed only once, immediately after creation or rotation. Acrity does not store the API key plaintext. To validate future calls, Acrity stores an HMAC-SHA-256 hash with pepper.

## Scopes

When creating a key, select only the required scopes.

| Scope                 | Typical use                                                 |
| --------------------- | ----------------------------------------------------------- |
| `Reviews.Read`        | list reviews, decisions, and findings                       |
| `Reviews.Write`       | request reviews through the API                             |
| `Repositories.Read`   | list and view connected repositories                        |
| `Repositories.Write`  | connect, update, or disconnect repositories through the API |
| `Credentials.Read`    | view credential metadata                                    |
| `Credentials.Write`   | create or change credentials through the API                |
| `Webhooks.Read`       | list configured webhooks                                    |
| `Webhooks.Write`      | create, change, or deactivate webhooks                      |
| `Workspaces.Read`     | view workspace context and data                             |
| `Workspaces.Write`    | change allowed workspace settings                           |
| `SecurityScans.Read`  | list and view security scans                                |
| `SecurityScans.Write` | start on-demand scans                                       |

Write scopes imply higher operational risk. Prefer a separate key for each automation.

## Expiration and IP allowlist

When creating an API key, configure:

* an expiration compatible with the automation's use — expiration is chosen at creation and cannot be changed later; to use a different validity period, create a new key;
* an IP allowlist when the integration runs on known infrastructure;
* a descriptive name with owner, system, and environment;
* the minimum required scopes.

## Rotation

Rotating an API key generates a new value and invalidates the previous secret. Update the secrets vault and consuming automation immediately after rotation.

<Steps>
  <Step title="Rotate in the Console">
    Go to `Console > API Keys`, find the key in the list, and choose `Rotate` from its row actions.
  </Step>

  <Step title="Store the new value">
    Copy the key displayed once to the secrets vault.
  </Step>

  <Step title="Update the automation">
    Update the secret used by the integration and restart the consuming service when needed.
  </Step>

  <Step title="Validate">
    Make a simple call to `/api/v1/context` to confirm authentication, scopes, and workspace.
  </Step>
</Steps>

## Common responses

| Status | Likely meaning                             | Action                                              |
| ------ | ------------------------------------------ | --------------------------------------------------- |
| `401`  | key missing, invalid, expired, or inactive | check the header and key state in the Console       |
| `403`  | key is valid, but lacks required scope     | add the scope or create a separate key              |
| `429`  | usage limit reached                        | reduce concurrency, apply backoff, and review usage |