Skip to main content
Sign in RESOURCES

Rotating Recurly API keys

Recurly
  • Updated

Recurly API keys authenticate server-to-server requests to the Recurly API (for example, creating accounts, fetching invoices, or updating subscriptions). Like any credential, API keys should be rotated periodically and immediately if you suspect compromise.

This guide explains a zero-downtime rotation approach: you create a new key, update your application(s) to use it, validate traffic, and then revoke the old key once you confirm everything is working.

Key takeaway: Avoid downtime by ensuring there is an overlap period where both the old and new API keys are valid while you roll out changes.

When to Rotate an API Key

  • Security policy: Your company requires scheduled credential rotation (e.g., every 90 days).
  • Employee changes: A team member with access leaves the organization.
  • Suspected compromise: You believe the key may have been exposed (logs, screenshots, leaked config, etc.).
  • Access hygiene: You want separate keys per environment (sandbox vs production) or per service.
Important: If you suspect compromise, rotate immediately and consider temporarily restricting or disabling the compromised key as soon as you have a safe rollout plan.

Prerequisites

Before rotating keys, make sure you know:

  • Which environment(s) you are rotating (Sandbox, Production, or both).
  • All applications/services that call Recurly (backend services, jobs/workers, integration middleware, etc.).
  • Where the key is stored (secret manager, environment variables, CI/CD, container platform, etc.).
ItemRecommendation
Separate keys per environmentUse different keys for sandbox and production to prevent cross-environment mistakes.
Separate keys per serviceCreate unique keys for each application (API service, worker, data pipeline) to reduce blast radius.
Secret storageStore keys in a secret manager; avoid committing keys into repositories or build logs.
Rollback planKeep the old key valid until the new key rollout is verified.

Rotation Steps (Zero-Downtime)

Step 1: Create a new API key in Recurly

  1. In your Recurly Admin Console, navigate to Integrations API Credentials
  2. Create a new API key for the correct environment (sandbox or production).
  3. Label it clearly (example: billing-api-prod-2026-02).
  4. Copy the key and store it securely (password manager / secret manager).
Tip: If you have multiple apps calling Recurly, consider creating one new key per app so you can rotate or revoke them independently later.

Step 2: Deploy the new key alongside the old key

Update your secret storage to include the new key, but do not revoke the old key yet. Your goal is to roll out the new key to all callers while the old key remains valid.

Step 3: Update applications to use the new key

Update each service that calls Recurly to use the new API key, then deploy.

  • Backend API services
  • Background jobs / workers
  • Data export / ETL pipelines
  • Integration middleware (if it authenticates to Recurly)
Note: If your architecture supports it, rotate one service at a time (canary rollout) and validate before proceeding.

Step 4: Verify traffic is using the new key

Confirm that requests are successfully authenticating with the new key. The specific method depends on your logging/monitoring setup. Common approaches include:

  • Application logs: confirm Recurly calls are returning 2xx responses.
  • Error monitoring: confirm there is no spike in 401 Unauthorized or 403 Forbidden.
  • Operational checks: run a small set of read-only and write actions in your normal workflow.

Step 5: Revoke (or disable) the old key

Once you are confident all services are using the new key, revoke/disable the old key in Recurly. This completes the rotation and reduces the chance of accidental fallback to the old credential.

Important: If you revoke the old key too early, any service still using it will begin failing immediately. Always validate first.

Validation Checklist

  • ✅ New key is created in the correct Recurly environment (sandbox vs production).
  • ✅ All services have been deployed with the updated secret/config.
  • ✅ No sustained 401/403 errors after rollout.
  • ✅ Core workflows succeed (examples: create account, create subscription, invoice collection flow).
  • ✅ Old key revoked only after confirming no remaining callers depend on it.

Common Pitfalls

  • Mixing environments: using a sandbox key in production (or vice versa).
  • Partial rollout: updating one service but forgetting a worker/cron job that also calls Recurly.
  • Config caching: services that require restart/redeploy to pick up the new secret.
  • Keys in logs: printing full keys in debug logs or error traces.

Troubleshooting

Symptoms: 401 Unauthorized / 403 Forbidden

  • Confirm the key is correct (no whitespace, correct environment).
  • Confirm the service has been redeployed/restarted and is reading the latest secret.
  • Check if the old key was revoked before all services were updated.

Symptoms: Some endpoints work, others fail

  • Confirm that all services are using the same updated key (no mixed deploys).
  • Check whether any batch jobs or scheduled tasks still reference the old key.
If you’re stuck: Capture the request ID / timestamp, the environment, and the affected endpoint(s), then contact Recurly Support with a short description of what changed during the rotation.

Related articles

Comments

0 comments

Please sign in to leave a comment.