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.

πŸ“˜

The API Key Policy is disabled by default.

API Key Policy

API Key Policy

Enable API Key Policy

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

Enable API Key Policy

Enable API Key Policy

Maximum permitted age (hours)The maximum permitted age of an account's API key.

Note: the minimum value this can be set to is β€œ24”.
DaysRead-only field, displaying the value of "Maximum permitted age (hours)" field in days.

For example, if the "Maximum permitted age (hours)" field is set to β€œ720” hours, this field will display β€œ30” days.
Enforce automatic API key refreshEnable to automatically refresh API keys that violate the policy. Take extreme caution when enabling this option, as this cannot be undone.

See section Enforce Automatic API Key Refresh for further details.

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.

Refresh API Key

Refresh API Key

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.

Enable API Key Policy with enforced automatic API key refreshing

Enable API Key Policy with enforced automatic API key refreshing

πŸ“˜

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.

Enable immediate for refresh of API keys

Enable immediate for refresh of API keys

Disable API Key Policy

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

Disable API Key Policy

Disable API Key Policy

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

Disabled Confirmation

Disabled Confirmation

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.

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

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


Cloudsmith is the new standard in Package / Artifact Management and Software Distribution

With support for all major package formats, you can trust us to manage your software supply chain.


Start My Free Trial Now
Cookie Declaration (Manage Cookies)