API Key Management Best Practices for SaaS Platforms
How to issue, scope, rotate, and revoke API keys securely — a complete guide for SaaS teams building service-to-service and CI/CD integrations.
API keys are everywhere. They power service-to-service communication, CI/CD pipelines, third-party integrations, and developer tooling. Yet most platforms treat API key management as an afterthought — handing out unscoped, never-expiring keys with full admin access. Here's how to do it right.
Why API Keys Still Matter
Even in a world of OAuth tokens and JWTs, API keys serve a crucial role. They're simple to use, don't require interactive login flows, and work well for server-to-server communication where there's no human in the loop. The key is treating them with the same rigor you'd apply to any other credential.
Principle 1: Scope Everything
An API key should have the minimum permissions needed for its purpose. If a CI/CD pipeline only needs to read user data for testing, it shouldn't have write access to organizations or the ability to modify SSO configurations.
In Calimatic Identity, every API key is scoped to specific permissions. When creating a key, you select exactly which operations it can perform:
users:read— Read user profiles and listsusers:write— Create, update, and deactivate usersorganizations:read— Read organization detailsroles:manage— Create and modify rolesaudit:read— Access audit logs
This granularity means a compromised key limits the blast radius to only the permissions it was granted.
Principle 2: Set Expiration Policies
Keys that live forever are keys that eventually leak. Every API key should have a defined expiration date. For most use cases, 90 days is a reasonable default. For sensitive operations, consider 30 days or shorter.
Calimatic Identity enforces expiration policies at the platform level. When a key nears expiration, the admin dashboard surfaces a warning. Expired keys are automatically deactivated — no manual intervention required.
Principle 3: Rotate Regularly
Rotation is the practice of replacing an active key with a new one on a regular schedule. This limits the window of exposure if a key is compromised without your knowledge.
Best practice: issue a new key before deactivating the old one. This creates an overlap period where both keys are valid, giving your services time to update their configuration without downtime.
Principle 4: Use Prefixes for Identification
A good API key format makes keys identifiable without revealing their full value. Calimatic Identity keys use the format cm_live_ or cm_test_ followed by a random string. This makes it easy to:
- Identify which platform a key belongs to
- Distinguish production keys from test keys
- Scan codebases and logs for accidentally committed keys
Principle 5: Log Everything
Every API key usage should be logged. This includes successful calls, failed authentication attempts, and operations performed. In Calimatic Identity, all API key activity flows through the audit log with the key's ID attached, so you can trace any action back to the specific key that performed it.
Principle 6: Provide Emergency Revocation
Sometimes a key needs to be killed immediately — a developer accidentally commits it to a public repository, a service is compromised, or an employee leaves the company. Your platform needs a way to revoke keys instantly.
Calimatic Identity supports immediate key revocation from both the admin dashboard and the API. Revoked keys are rejected on the next request with no cache delay.
Common Anti-Patterns to Avoid
Sharing keys across services — Each service should have its own key with its own scopes. If one service is compromised, you can revoke its key without affecting others.
Storing keys in code — Keys belong in environment variables, secret managers, or vault services. Never hardcode them, even in private repositories.
Granting admin scopes by default — Start with the minimum permissions and add more only when needed. It's easier to expand access than to restrict it after a breach.
Ignoring unused keys — Regularly audit your active keys. If a key hasn't been used in 30 days, it's probably safe to revoke it. Calimatic Identity's admin panel shows last-used timestamps for every key.
Getting Started
Calimatic Identity's API key management is available on all plans. Create your first scoped key in the admin panel under API Keys, or use the REST API to manage keys programmatically. Check our documentation for integration examples and best practices for popular frameworks and CI/CD platforms.