4.3.2 Integrations — API Keys & Tokens — Rotation & Revocation — Best Practices

Rotation and revocation are essential controls for limiting the blast radius of compromised credentials and maintaining long-term security hygiene. Praisma Hub provides deterministic mechanisms to rotate keys without downtime and to revoke access immediately when required.

Rotation Strategy

Key rotation replaces an existing credential with a new one while allowing dependent systems to transition safely.

Rotation principles:

Overlapping validity periods

Explicit activation and deactivation

No forced downtime

Recommended flow:

Create a new key with identical scopes

Update external systems to use the new key

Revoke the old key after verification

Automated Rotation

For supported environments, rotation can be automated through scheduled jobs or external secret managers.

Automation characteristics:

Predictable rotation intervals

Audit logging for each rotation

No exposure of old secrets

Example scheduled rotation:

ApiKeyRotator::schedule($key, interval: '90d');

Revocation Scenarios

Keys may be revoked for multiple reasons.

Common scenarios:

Suspected compromise

Employee or system offboarding

Scope reduction or policy change

Integration decommissioning

Revocation takes effect immediately across all services.

Revocation Execution

Revocation invalidates the key without deleting historical usage data.

Example revocation:

$apiKey->revoke('suspected_compromise');

Graceful Failure Handling

Revoked or expired keys result in deterministic authentication failures. Error responses do not disclose sensitive information.

Typical response behavior:

HTTP 401 for invalid keys

Clear error codes

No partial execution

Monitoring and Alerts

Security-sensitive events such as repeated failures or unexpected usage patterns may trigger alerts.

Monitored signals:

Authentication failure spikes

Usage outside expected scope

Access after scheduled expiration

Audit and Compliance

All rotation and revocation actions are logged with actor, timestamp, and reason. Logs support security reviews and compliance audits.

Security and Isolation

Rotation and revocation operations are tenant-scoped and permission-guarded. No user can rotate or revoke keys beyond their authorized scope.