Credential rotation

Rotate credentials without printing them, placing them in shell history or committing them. Use the provider's secret manager or a root-readable environment file with mode 0600, then record only the credential ID, operator and time.

Standard sequence

1. Identify every consumer and the owner of the credential.
2. Create a replacement with the minimum required scope.
3. Stage dual credentials when the provider supports overlap.
4. Update consumers and restart or reload them safely.
5. Verify authentication, readiness and the relevant business flow.
6. Revoke the old credential.
7. Inspect provider audit logs and record completion.

If a credential may have been exposed, revoke it promptly and inspect usage before treating normal rotation as complete.

MicroAuth keys

Tenant SDK secret (mas_)

Create or rotate the secret in the tenant administration UI. Update every API process through its secret store, restart workers in a controlled sequence and verify snapshot plus usage reporting. The old secret can stop working immediately, so plan a maintenance window unless the API explicitly supports overlap.

Workspace API key (mak_)

Create a second scoped key, update billing and back-office callers, verify management requests, then revoke the old key. Give each integration its own key so one rotation does not interrupt unrelated systems.

Customer API key (map_)

Create a replacement, update the customer's client, verify it, then revoke the old key. Never copy raw customer keys into support tickets or logs. The API stores hashes, so a lost raw key cannot be recovered.

Stripe credentials

Stripe API secrets and webhook signing secrets are different credentials. Rotate and test them separately.

For a tenant or the MicroAuth platform account:

1. verify the expected Stripe account ID before saving a new API secret;
2. update the encrypted secret and run a read-only account check;
3. create or roll the webhook endpoint signing secret;
4. send a signed test event and confirm durable inbox processing;
5. retain the old endpoint only long enough to drain events;
6. revoke the old API key and remove the old webhook endpoint;
7. run reconciliation for the overlap window.

Do not disconnect Stripe or clear local subscription IDs while live subscriptions remain unresolved.

Application encryption key

The application encryption key protects stored Stripe and other reversible secrets. It cannot be replaced as a simple environment-variable swap.

Use a key version:

1. deploy code that can decrypt the old and new versions;
2. make new writes use the new version;
3. re-encrypt every stored ciphertext transactionally and verify counts;
4. remove old-key reads in a later release;
5. destroy the old key only after backups and rollback windows no longer require it.

Losing this key can make encrypted credentials unrecoverable. Suspected exposure requires rotating the downstream credentials too.

Infrastructure and delivery credentials

Apply the standard overlap sequence to Brevo, object storage, Cloudflare, database, Redis, GitHub deployment and SSH credentials. Prefer workload identity or narrowly scoped short-lived credentials over reusable root keys. Pin SSH host keys and use an unprivileged deployment account.

Verification

• old credentials fail after revocation;
• new credentials work only for their intended scope;
• logs and audit events contain no secret values;
• /readyz, worker jobs and webhook processing are healthy;
• snapshot, usage, email, upload and deployment smoke tests pass as relevant;
• provider audit logs show no unexplained access.