API Key Policy

API Key Policy Overview

The API key policy allows organizations to customize the maximum age of API keys across all organizational accounts, by specifying the duration after which keys should be rotated. This ensures that API keys older than the designated age are invalidated for authentication, with the added flexibility to enforce a refresh for keys that exceed the specified duration.

View API Key Policy

To view your organization's API Key Policy, go to your organization's “Settings” page and select "Authentication Policies" from the left-hand menu.

📘

Note

The API Key Policy is disabled by default.

Enable API Key Policy

To enable the API Key Policy, set the "Maximum permitted age (hours)" field and click "Update".

Once the policy is enabled, permission will be revoked for any API key older than the specified maximum age. This applies to all accounts associated with the organization, including members, managers, owners, service accounts, and collaborators.

If a user attempts to utilize an API key that violates the policy, they will receive a "permission denied" error message

To regain access, the user should update their API Key by clicking "Refresh" within the API settings page.

Enforce Automatic API key Refresh

🚧

Exercise extreme care when utilizing this option, as refreshing an API key is an irreversible action.

To automatically force refresh an API key that violates the policy, enable "Enforce automatic API key refresh".

📘

This force refreshes API keys of all users (member, manager, owners and service accounts) that violate the policy, except for collaborators.

📘

The process of force refreshing all API keys may take up to 60 minutes to complete.

To enforce an immediate refresh of API keys that violate the policy, enable both the "Enforce automatic API key refresh" and "Refresh immediately" options.

Disable API Key Policy

To disable the API key policy, clear the value within the "Maximum permitted age (hours)" field and click "Update".

The UI will then update to confirm the Policy has been disabled.

Once disabled, restrictions to API keys that previously violated the policy are lifted and these API keys will become operational again.

Members of Multiple Organizations

If a user is a member of multiple organizations the user's permissions will only be revoked for the organization where the API key policy is enforced and their API key violates the policy. Their permissions in all other organizations are unaffected.

However, if the user is a member of an organization which also has "Enforce automatic API key refresh" enabled, the user's API key will be refreshed across all their organizations.

Notifications

When an API key is approaching its expiration age, users will receive a notification at least 24 hours in advance. This notification will be sent via email and will also appear as a notification when they log into the application.

Additionally, users will receive an email and UI notification when their API key has expired.

If the API policy is enabled and "Enforce automatic API key refresh" is set, users will also receive an email notification when their API key has been refreshed. This email will include details about the user who initiated the refresh process.

For service accounts, the creator of the service account will receive an email notification informing them of the upcoming expiration of the service's API key. The email also provides a URL that the user can use to reset the API key. Additionally, when the creator logs into the application's user interface, they receive a warning message.

If a service account has been created by another service account, no email notification will be sent for an upcoming API key expiration. In this scenario, with the API Key Policy enabled, you can use the Get a list of all services within an organization REST API call to retrieve your services, and find each respective key expiry in the key_expires_at field.

Audit Logs

All actions and notifications related to the API Key Policy are also logged within the Audit logs.

Notifications of API keys expiring soon:

Expired API keys:

API key refreshed by the user:

API key force refresh:

In scenarios where a user is a member of multiple organizations, it is important to note that the user who enforces the API key refresh will only be visible as the initiator within the organization where they hold the ownership role. In other organizations where the user is a member, the API key refresh action will still be recorded in the audit logs. However, the user who enforced the refresh will be obscured, and the action will be listed as a "refreshed API key" rather than an "enforced API key refresh."