Skip to main content
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.
Store the key in a secure vault when it is created. After the screen is closed, the complete key cannot be displayed again.

​
Main fields

FieldPurpose
NameIdentifies the key and the system that uses it.
ExpirationDefines until when the key can be used. Set only when the key is created; it cannot be edited afterward.
IP allowlistRestricts use to allowed addresses or ranges when applicable.
ScopesLimit which areas of the API the key can access.
ActiveIndicates whether the key can be used.
Last charactersHelps identify the key without exposing the secret.

​
Create an API Key

1

Open API Keys

Go to Console > API Keys.
2

Create new

Choose New API Key.
3

Name it

Use a name that identifies the system, environment, and integration owner.
4

Set expiration

Choose a validity period. Expiration is set only at creation and cannot be changed later.
5

Configure IP allowlist

Restrict the key to expected IPs when possible.
6

Choose scopes

Grant only the required scopes.
7

Save and store

Copy the key shown once and store it in a secure vault.

​
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.
Expiration is set only when the key is created and cannot be edited afterward. To use a different expiration, create a new key.

​
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

ScopeAllows
ReviewsRead or operate review-related resources according to the granted level.
WorkspacesRead or change workspace data according to the granted level.
CredentialsRead or change credential metadata according to the granted level.
WebhooksRead or change webhooks according to the granted level.
RepositoriesRead or change repositories according to the granted level.
SecurityScansRead 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.
After rotation, the previous secret stops working. Plan the change to avoid interruption.

​
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

SymptomWhat to check
Key does not authenticateConfirm copied value, expiration, active status, and correct environment.
Access deniedCheck scopes and workspace role.
Works locally, fails in productionCheck IP allowlist and the real request origin.
I lost the complete keyRotate the key and update the integration.
Integration stopped after rotationUpdate 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.