> ## 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 Keys

> Create and manage programmatic access keys for the Acrity public API.

API Keys let external systems access the Acrity public API on behalf of a workspace.

Use `Console > API Keys` to create, edit metadata, activate, deactivate, rotate, and remove keys.

## When to use

Use API Keys when:

* an automation needs to query Acrity data;
* an internal system needs to trigger operations supported by the public API;
* integrations need stable workspace-level authentication;
* webhooks are not enough because the external system needs to fetch data on demand.

Use webhooks when the external system only needs to receive events.

## Who can access

Managing API Keys requires a Workspace admin (platform admins also have access). Creating an API key also requires a Workspace admin.

## Authentication format

External systems should send the key as described in the public API documentation. The creation screen shows the complete key only once.

<Warning>
  Store the key in a secure vault when it is created. After the screen is closed, the complete key cannot be displayed again.
</Warning>

## Main fields

| Field           | Purpose                                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| Name            | Identifies the key and the system that uses it.                                                          |
| Expiration      | Defines until when the key can be used. Set only when the key is created; it cannot be edited afterward. |
| IP allowlist    | Restricts use to allowed addresses or ranges when applicable.                                            |
| Scopes          | Limit which areas of the API the key can access.                                                         |
| Active          | Indicates whether the key can be used.                                                                   |
| Last characters | Helps identify the key without exposing the secret.                                                      |

## Create an API Key

<Steps>
  <Step title="Open API Keys">
    Go to `Console > API Keys`.
  </Step>

  <Step title="Create new">
    Choose `New API Key`.
  </Step>

  <Step title="Name it">
    Use a name that identifies the system, environment, and integration owner.
  </Step>

  <Step title="Set expiration">
    Choose a validity period. Expiration is set only at creation and cannot be changed later.
  </Step>

  <Step title="Configure IP allowlist">
    Restrict the key to expected IPs when possible.
  </Step>

  <Step title="Choose scopes">
    Grant only the required scopes.
  </Step>

  <Step title="Save and store">
    Copy the key shown once and store it in a secure vault.
  </Step>
</Steps>

## Expiration

Expiration options can include:

* no expiration;
* 1 hour;
* 1 day;
* 7 days;
* 30 days;
* 90 days;
* 180 days;
* 360 days.

Prefer a defined expiration for temporary integrations, tests, or non-production environments.

<Note>
  Expiration is set only when the key is created and cannot be edited afterward. To use a different expiration, create a new key.
</Note>

## IP allowlist

IP allowlist limits key usage to known origins.

Use it when:

* the integration runs on infrastructure with a fixed IP;
* the organization requires origin control;
* the key has write scopes;
* the integration is critical.

Review the allowlist after infrastructure, NAT, proxy, or cloud provider changes.

## Scopes

| Scope         | Allows                                                                   |
| ------------- | ------------------------------------------------------------------------ |
| Reviews       | Read or operate review-related resources according to the granted level. |
| Workspaces    | Read or change workspace data according to the granted level.            |
| Credentials   | Read or change credential metadata according to the granted level.       |
| Webhooks      | Read or change webhooks according to the granted level.                  |
| Repositories  | Read or change repositories according to the granted level.              |
| SecurityScans | Read or operate security scan resources according to the granted level.  |

Write scopes usually include the corresponding read capability. Grant write access only when the integration truly needs to change data.

## Rotate a key

Rotation generates a new secret for the same logical key.

Recommended flow:

1. Go to `Console > API Keys`.
2. In the keys list, find the key and choose `Rotate` from its row actions.
3. Confirm the rotation in the dialog.
4. Copy the new displayed value.
5. Update the external system.
6. Validate the integration.
7. Remove old secrets from the vault or runtime environment.

<Warning>
  After rotation, the previous secret stops working. Plan the change to avoid interruption.
</Warning>

## Deactivate or delete

Deactivate a key when you want to temporarily interrupt access without losing administrative history.

Delete it when:

* the integration was removed;
* the system no longer exists;
* the key was created by mistake;
* the organization's policy requires permanent removal.

## Best practices

* Create one key per system and environment.
* Use clear names, such as `billing-sync-prod`.
* Apply the smallest possible scope.
* Configure expiration when practical.
* Use IP allowlist for critical integrations.
* Store it in a secure vault, never in source code.
* Rotate periodically.
* Deactivate unused keys.

## Common issues

| Symptom                            | What to check                                                             |
| ---------------------------------- | ------------------------------------------------------------------------- |
| Key does not authenticate          | Confirm copied value, expiration, active status, and correct environment. |
| Access denied                      | Check scopes and workspace role.                                          |
| Works locally, fails in production | Check IP allowlist and the real request origin.                           |
| I lost the complete key            | Rotate the key and update the integration.                                |
| Integration stopped after rotation | Update the secret in the external system and redeploy when needed.        |

## Security

The complete secret is shown only once and should not be stored in plaintext outside a secure vault. Technical protection for keys and tokens is described in `Security > Credentials and tokens`.