Guides
  1. ONBOARDING AND SECURITY

Credentials & Key Rotation

This page covers the operational side of managing your credentials over time: what to rotate, when, and how the pieces fit together. For the initial issuance process, see Onboarding Overview & Checklist and mTLS Certificates & CSR.

Your credential inventory

As covered in Program Architecture and Authentication & Environments, each environment (staging, production) and each scope (Tenant, Program) has its own independent set of credentials:

CredentialScopeLifetimeRotation trigger
mTLS client certificateTenant or Program, per environment90 daysExpiry reminders (30/15/5 days) — see below
X-API-KeyTenant or Program, per environmentNo fixed expiryPeriodic rotation as a security best practice, or immediately on suspected compromise
📘

Certificates and API keys rotate independently of each other — renewing your certificate does not require (or cause) a new API key, and vice versa. Track both separately. A simple internal register — one row per environment/scope, with issue date, expiry date (for certificates), and last-rotated date (for API keys) — is enough for most integrations.

Certificate renewal workflow

Certificates are valid for 90 days, with expiry reminders at 30, 15, and 5 days before expiry (delivered as described in Webhooks & Callback Notifications). The recommended workflow, starting from the 30-day reminder:

sequenceDiagram
    participant Axys
    participant You

    Note over Axys,You: T-30 days
    Axys->>You: Reminder — certificate expires in 30 days
    You->>You: Generate new key pair + CSR
    You->>Axys: Submit new CSR
    Axys->>You: New certificate issued (~24h)
    You->>You: Deploy new certificate alongside the old one (overlap)
    You->>Axys: Test request using the new certificate
    Axys->>You: 200 OK
    You->>You: Retire the old certificate and private key
    Note over Axys,You: T-0 — old certificate would have expired

Because the old certificate remains valid throughout the overlap period, there's no requirement to synchronize the cutover precisely — you can deploy the new certificate, verify it works, and retire the old one on your own schedule, as long as it's comfortably before expiry. For the step-by-step commands, see Rotate mTLS Certificates.

🚧

If a certificate lapses without renewal, every request using it will fail at the TLS handshake — before your X-API-Key is even checked, and before any application-level error handling on your side can run. Treat the 30-day reminder as the trigger to start renewal, not the deadline to finish it.

API key rotation

📘

Self-service API key rotation is part of the platform's Account Management tenant-management capabilities. API key issuance and rotation are handled through your Axys onboarding/account contact.

When rotating an API key (whether on a routine schedule or in response to a suspected compromise):

  1. Request a new API key for the affected scope (Tenant or Program) and environment.
  2. Update your application's configuration/secrets store with the new key.
  3. Deploy and verify the new key is working.
  4. Request revocation of the old key.

If you suspect a key has been compromised, treat steps 1 and 4 as urgent — request both the new key and the old key's revocation as part of the same request, rather than waiting for a routine rotation cycle.

Storage and access

Both credential types should live in a secrets manager appropriate to your infrastructure, loaded at runtime, and never committed to source control or embedded in client-side code. See Security Compliance & Data Protection for the platform's own custody and key-management architecture, and the broader principle-of-least-privilege guidance for your integration.

What's next