Secrets Rotation

Overview

DMTR integrations rely on credentials (API keys, OAuth secrets, webhook signing keys) that must be rotated periodically for security. This document describes credential types, rotation schedules, and procedures for automated and manual rotation. Follow these practices to maintain integration security and avoid service disruption during rotation.

Credential types

Credential types include API keys (server-to-server), OAuth client secrets (user-delegated flows), webhook signing secrets (event verification), and database or service account credentials. Each type has different rotation requirements and procedures. API keys support multiple active keys during rotation; OAuth secrets typically require coordinated rotation.

Rotation schedule

Rotation schedules vary by credential type and risk level. API keys should be rotated at least annually; OAuth secrets every 90 days for high-sensitivity integrations. Webhook signing keys follow the same schedule as API keys. Ad-hoc rotation is required after suspected compromise or personnel changes. Schedule rotations during low-traffic periods when possible.

Automated rotation

Automated rotation is supported for API keys via the DMTR API; new keys can be generated and old keys deprecated with a grace period. Integrate rotation into your CI/CD or secrets management pipeline. Use the rotation API to create new credentials and update your configuration before revoking the old ones. Monitor for failed requests during the transition.

Manual rotation

Manual rotation is required when automated rotation is not available or for OAuth secrets. Follow the step-by-step procedure: generate new credentials, update configuration in a controlled deployment, verify the integration works with new credentials, then revoke the old credentials. Document the procedure and assign ownership for each integration.

Revocation

Revocation immediately invalidates credentials and should be used in response to compromise or when decommissioning an integration. Revoked credentials cannot be restored; generate new credentials if the integration will continue. After revocation, monitor for unauthorized access attempts and update all systems that may have cached the old credentials.