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

# Managing API Keys

> Create, scope, rotate, and revoke API keys in Settings > Developers.

## Where to find API keys

In the Arcus app, navigate to **Settings > Developers > API Keys**. You must have the `settings.edit` permission on your account.

## Creating a key

1. Click **Create API key**
2. Enter a descriptive name (e.g. `WMS integration - production`)
3. Choose a mode: **Test** (sandbox data) or **Live** (real data)
4. Select scopes -- grant only what the integration needs
5. Optionally set an expiry date and IP allowlist
6. Click **Create**

The key is shown once. Copy it to your secrets manager immediately.

## Choosing scopes

Grant the minimum scope required. Common patterns:

| Integration                   | Recommended scopes                                                |
| ----------------------------- | ----------------------------------------------------------------- |
| Read-only analytics / BI tool | `accounts:read`, `orders:read`, `products:read`, `inventory:read` |
| Order import (one-way)        | `orders:write`, `accounts:read`, `products:read`                  |
| Warehouse management system   | `orders:read`, `fulfillment:write`, `inventory:write`             |
| Full ERP-to-ERP integration   | All read + write scopes                                           |
| Migration (one-time)          | All write scopes; revoke after migration completes                |

## IP allowlists

For server-to-server integrations, add your server's IP address or CIDR range. Requests from unlisted IPs return `403 Forbidden` with `code: ip_not_allowlisted`.

Leave the allowlist empty for integrations running on dynamic IPs (e.g. serverless functions, CI/CD pipelines).

## Key rotation

Rotate keys periodically or immediately after a suspected exposure:

1. Create a new key with the same scopes
2. Deploy the new key to your integration (update your secrets manager)
3. Verify the integration is using the new key (check your server logs for `request_id` patterns from the new key)
4. Delete the old key in **Settings > Developers > API Keys**

Key deletion is immediate and irreversible.

## Auditing key usage

The **Settings > Developers > Logs** tab shows every API request made with each key: timestamp, endpoint, status code, `request_id`, and IP address. Use this to:

* Verify a new key is being used after rotation
* Investigate unexpected 4xx errors
* Check if an unused key can be safely deleted

## Revoking a key

Click the trash icon next to the key in **Settings > Developers > API Keys**. Confirm the deletion. All in-flight requests using that key immediately start returning `401 Unauthorized`.

## Security best practices

* Store API keys in your platform's environment variables or a dedicated secrets manager -- never in source code or committed config files
* Restrict high-privilege keys to specific IP addresses
* Audit usage regularly in the Logs tab
* Rotate keys every 90 days; revoke one-time migration keys as soon as the migration completes