Skip to main content
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: 
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/context"
Do not send API keys in query strings, logs, screenshots, or support tickets. Use headers and a secrets vault.

​
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.
ScopeTypical use
Reviews.Readlist reviews, decisions, and findings
Reviews.Writerequest reviews through the API
Repositories.Readlist and view connected repositories
Repositories.Writeconnect, update, or disconnect repositories through the API
Credentials.Readview credential metadata
Credentials.Writecreate or change credentials through the API
Webhooks.Readlist configured webhooks
Webhooks.Writecreate, change, or deactivate webhooks
Workspaces.Readview workspace context and data
Workspaces.Writechange allowed workspace settings
SecurityScans.Readlist and view security scans
SecurityScans.Writestart 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.
1

Rotate in the Console

Go to Console > API Keys, find the key in the list, and choose Rotate from its row actions.
2

Store the new value

Copy the key displayed once to the secrets vault.
3

Update the automation

Update the secret used by the integration and restart the consuming service when needed.
4

Validate

Make a simple call to /api/v1/context to confirm authentication, scopes, and workspace.

​
Common responses

StatusLikely meaningAction
401key missing, invalid, expired, or inactivecheck the header and key state in the Console
403key is valid, but lacks required scopeadd the scope or create a separate key
429usage limit reachedreduce concurrency, apply backoff, and review usage