API Key Management Best Practices

Why API Key Management Matters

API keys are the authentication credentials your AI agents use to communicate with Intended. They are the proof that an agent is who it claims to be. If an API key is compromised, an attacker can submit intents on behalf of the agent, potentially obtaining authority tokens for unauthorized actions.

API key management is not glamorous work. It is the plumbing that keeps the system secure. But poor key management is one of the most common causes of security incidents across the industry. Keys are leaked in Git commits, stored in plaintext configuration files, shared across environments, and never rotated.

Here are the practices that keep API keys secure in a governance-critical system.

Scoping: Least Privilege for Keys

Every API key should have the minimum permissions required for its purpose. Intended supports key scoping across three dimensions.

**Domain scope.** A key can be restricted to specific MIR domains. An agent that only performs SDLC operations should have a key scoped to the SDLC domain. If the key is compromised, the attacker can only submit SDLC intents, not infrastructure or data management intents.

**Environment scope.** A key can be restricted to specific environments. A staging agent should have a key scoped to staging. This prevents a compromised staging key from being used to submit production intents.

**Action scope.** A key can be restricted to specific action types within its domain scope. An agent that only performs code deployments can be restricted to `sdlc.deployment.*` actions, preventing the key from being used for other SDLC actions.

The combination of domain, environment, and action scoping creates a tight permission boundary around each key. Even if a key is compromised, the blast radius is limited to the key's scope.

Rotation: Regular and Automated

API keys should be rotated regularly. The rotation interval depends on your risk tolerance and operational requirements. Intended recommends rotation every 90 days for standard keys and every 30 days for keys with high-privilege scopes.

Automated rotation eliminates the human overhead and ensures rotation actually happens. Intended supports automated rotation through the API and CLI. Here is the rotation workflow.

Step 1: Generate a new key for the agent. The old key remains active. The agent now has two valid keys.

Step 2: Update the agent's configuration to use the new key. This might be a Kubernetes secret update, a configuration management change, or an environment variable update.

Step 3: Verify the agent is using the new key. Check the Intended dashboard or API to confirm that recent requests from the agent are authenticated with the new key.

Step 4: Revoke the old key after a grace period (see below).

This workflow ensures zero-downtime rotation. At no point during the rotation process is the agent unable to authenticate.

Grace Periods: Safe Transitions

The grace period is the time between generating a new key and revoking the old key. During the grace period, both keys are valid. This is important because key rotation is not instantaneous. Configuration changes take time to propagate. Agent processes may cache the old key. Deployment pipelines may have the old key in flight.

Intended supports configurable grace periods from 1 hour to 30 days. The recommended grace period depends on your deployment model.

For agents running in Kubernetes with automated secret management: 1-4 hours. Secret updates propagate quickly, and pod restarts pick up new keys automatically.

For agents with manual configuration management: 24-48 hours. This gives the operations team time to update configurations across all environments.

For agents in air-gapped or restricted environments: 7-14 days. Updates in these environments may require manual processes with longer lead times.

During the grace period, Intended logs which key each request uses. This lets you verify that the transition is progressing: as agents pick up the new key, requests authenticated with the old key should decrease to zero.

Storage: Never in Code

API keys must not be stored in source code, configuration files committed to Git, or any location accessible to unauthorized parties. This seems obvious, but key leakage through code repositories remains one of the most common credential exposure vectors.

Recommended storage locations: Kubernetes secrets (encrypted at rest), cloud secret management services (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault), HashiCorp Vault, or environment variables injected at runtime by your deployment pipeline.

Intended provides integrations with common secret management systems. The integration automates key rotation by generating new keys in Intended and storing them directly in your secret management system, without the key ever appearing in logs, configuration files, or human-readable output.

Monitoring: Know When Something Is Wrong

Key monitoring detects compromise indicators and operational issues before they become incidents.

**Authentication failure monitoring.** Track failed authentication attempts per key. A spike in failures may indicate a compromised key being used from an unfamiliar location, a key rotation that was not completed (the agent is still using the revoked key), or a misconfiguration in the agent's key retrieval.

**Usage pattern monitoring.** Track request patterns per key. A key that normally authenticates 100 requests per hour suddenly authenticating 10,000 requests per hour is an anomaly. A key that normally authenticates requests from a single IP authenticating from multiple IPs is an anomaly.

**Scope violation monitoring.** Track when a key attempts to authenticate a request outside its scope. If a key scoped to SDLC submits an infrastructure intent, that is a scope violation. The request is denied, but the attempt itself is a signal worth investigating.

Intended provides all three monitoring signals through the metrics endpoint and the console dashboard. Alerts can be configured for each signal.

Emergency Revocation

When a key is known or suspected to be compromised, it must be revoked immediately. Intended supports instant revocation through the console, CLI, and API.

When a key is revoked, all subsequent authentication attempts using that key are rejected immediately. There is no grace period for emergency revocation. Any in-flight requests that have already been authenticated will complete, but no new requests will be accepted.

After emergency revocation, generate a new key and update the agent's configuration through your standard deployment process. Monitor the agent's authentication logs to confirm the transition.

Maintain a documented runbook for emergency key revocation. The runbook should include who is authorized to revoke keys, how to revoke via console, CLI, and API, how to generate and deploy replacement keys, how to investigate the compromise, and who to notify.

Key Lifecycle Summary

The full API key lifecycle: generate with appropriate scope, store in a secret management system, deploy to the agent through your configuration pipeline, monitor usage patterns and authentication failures, rotate on a regular schedule with grace periods, and revoke immediately if compromised.

Good key management is invisible when it works. The agents authenticate, the governance decisions flow, and nobody thinks about keys. But invisible security is not accidental security. It is the result of deliberate practices, automated processes, and continuous monitoring.