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

​
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

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

​
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.