Workspaces

API key rules

API key rules allow workspaces to customize the maximum age of API keys across all workspace accounts, by specifying the duration after which keys should be rotated. Frequent API key rotation 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.

Early access

The API key rules feature is in early access; if you would like to try this feature, please Contact Us.

View API key rules

To view your workspace's API key rules, go to the Settings tab of your Cloudsmith dashboard and click API key rules.

Note

API key rules are disabled by default.

Enable API key rules

To enable API key rules for a workspace, set the Maximum permitted age (hours) field and click Update policy.

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

If a user attempts to use an API key that violates the rules, they will receive a "Permission denied" error message.

To regain access, the user should update their API key by clicking Refresh on the API settings page.

Enforce automatic API key refresh

API key refresh

Refreshing an API key is irreversible. Exercise extreme care when using this option.

To automatically force refresh an API key that violates the rules, enable Enforce automatic API key refresh:

Note

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

Note

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 rules, enable both the Enforce automatic API key refresh and Refresh immediately options:

Disable API key rules

To disable API key rules for a workspace, clear the value within the Maximum permitted age (hours) field and click Update policy:

The UI will then update to confirm the rules have been disabled:

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

Members of multiple workspaces

If a user is a member of multiple workspaces, their permissions will only be revoked for the workspace where the API key rules are enforced and their API key violates the rules. Their permissions in all other workspaces are unaffected.

However, if the user is a member of a workspace which also has Enforce automatic API key refresh enabled, their API key will be refreshed across all their workspaces.

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 rules are 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 API key rules enabled, you can use the Get a list of all services within a workspace 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 API key rules are also logged within the audit logs.

In scenarios where a user is a member of multiple workspaces, it is important to note that the user who enforces the API key refresh will only be visible as the initiator within the workspace where they hold the ownership role. In other workspaces where the user is a member, the API key refresh action will still be recorded in the audit logs, but 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."

Updated yesterday