API Key Rotation and Management

Overview

API keys provide secure authentication for accessing the Sturdy Statistics API. Each API key consists of four elements:

• Key Name – A unique identifier chosen at creation, which persists across rotations.

• Key ID – A fixed identifier for logging and management.

• Key Value – A Base64-encoded cryptographic token required for authentication. This is displayed only once and cannot be recovered if lost.

• Expiration Date – Defines when the key automatically expires, unless manually rotated or revoked.

API keys function as bearer tokens, meaning anyone in possession of an API key can use it to perform any action authorized for that key; this may include accessing, modifying, or deleting data, or changing permissions. API keys must be treated as sensitive credentials, like passwords, and stored securely.

Compromised API keys may result in unauthorized access, data exfiltration, quota depletion, or service disruption. To mitigate these risks, you must follow secure key management practices and rotate keys regularly.

This document outlines best practices for API key management and describes the available features for controlling the lifecycle of your API keys to maintain security.

Key Management Features

You can manage API keys using either the web portal or the keys API.

• Web Portal: Requires OAuth2.1 authentication.

• API Management: Requires API calls authenticated with an active, non-expired master key. If your organization lacks a master key, you must create one using the web portal.

Provisioning API Keys

When creating a new API key, you must:

• Assign a key name: The name must be unique within your organization. Use descriptive names (e.g., prod-backend, dev-Andy) for easier management. The key name persists across rotations until revoked.

• Choose a key type:

  • Standard key: Limited to the indices it creates or is explicitly granted access to.
    
  • Master key: Grants full permissions to all organization indices and enables API-based key management. Use sparingly and protect rigorously. Most organizations do not require a master key.

• Set a lifespan:

  • Web Portal: Choose 1-month, 3-month, or 1-year duration.
    
  • API: Specify any lifespan in seconds (up to 1 year or 3.1547e7 seconds).

• Securely store the key value:

  • The key value is displayed only once at creation.
    
  • It is not stored, and cannot be recovered if lost.
    
  • If lost, rotate the key to generate a new value.

• Optional: Note the Key ID:

  • Each key has a unique ID that remains unchanged across rotations.
    
  • Once revoked, logs for the key are only accessible using its Key ID.

Managing Key Permissions

Each API key can be granted different levels of access per index:

By default:

• Standard keys: Have manage permissions on indices they create but no other access unless explicitly granted.

• Master keys: Have manage permissions on all organization indices.

Because Master Keys have elevated privileges, they should only be used when necessary (e. g., for programmatic key management) and must be stored securely. For added security, pause Master Keys when not in use.

Key Lifecycle

Revoking Keys

You can revoke an API key at any time via the web UI or API. Revocation is immediate and irreversible:

• The key is permanently deleted and cannot be reactivated.
  
• Logs for the key remain accessible only via its Key ID.
  
• Permissions associated with the key are lost.

Alternatives to revocation:

• Pause the key: Temporarily disable all access, while retaining permission settings and logs.

• Rotate the key with no grace period: Immediately replace its value, invalidating any stolen copies.

Only revoke a key if:

• It is no longer in use, and
  
• Its logs and permissions are no longer needed.

Pausing and Resuming Keys

If you need to temporarily disable a key:

• Pause it: Click the “Pause” button in the web UI. This action takes effect immediately, and it suspends all access until resumed.

• Resume it: Click the “Resume” button to reactivate the key.

Pausing is ideal for troubleshooting, security audits, or temporary offboarding.

Rotating API Keys

Regular key rotation reduces security risks by replacing an old key value with a new one.

• Grace Period:
  • Both old and new key values remain valid during a transition period. This enables you to rotate the key without experiencing a service interruption.
    
  • Default: 1 hour.
    
  • Can be set up to 2 weeks, or 0 for immediate rotation.
    
• Key Lifespan:
  • Optionally update the key’s lifespan during rotation.
    
  • If unspecified, the original lifespan is retained.

To rotate a key: 1) use the “Rotate” button in the web portal or call the rotation API endpoint, 2) Deploy the new key value to your application before the grace period expires in order to avoid any interruption of service, and 3) Remove all references to the old key value to prevent unintended usage.

Best Practices for Secure Key Management

1. Use a unique API key for each team member or project:

   • Assigning unique keys enables granular permissions and usage tracking.
     
   • Pause or Revoke individual keys when access is no longer needed.

2. Rotate keys regularly: For most organizations, a 3-month lifespan balances security and convenience.

3. Monitor key usage:

   • Regularly review key activity to detect anomalies.
     
   • If you suspect a leak, immediately rotate the key.

4. Grant minimal permissions: Follow the principle of least privilege.

5. Limit master key usage: Master keys have broad privileges and should be tightly controlled. Most organizations do not need to use master keys.

6. Store keys securely:

   • Never hard-code keys in source code.
     
   • Use environment variables or secret management tools.
     
   • Never expose keys in client-side environments (e.g., web browsers, mobile apps).

7. Ensure smooth key rotation: Use grace periods to transition without downtime.

Conclusion

Effective API key management is essential for maintaining security, availability, and data integrity. By leveraging Sturdy Statistics’ built-in security features and following best practices, you can minimize risk and ensure uninterrupted service.