Credential Rotation

Your API credentials are automatically rotated every 180 days. No downtime required.

Quick Facts

What: New credentials generated 30 days before expiration
When: Every 180 days
Downtime: Zero — both credentials work during transition
Your action: Update config anytime within 30 days

Rotation Timeline

Day 0          Day 150               Day 180               Day 210
  │                │                     │                     │
  │  Current credentials active          │                     │
  │◄──────────────────────────────────►│                     │
  │                │                     │                     │
  │                │  ← Email notification                     │
  │                │  ← New credentials ready                  │
  │                │                     │                     │
  │                │  ◄────── 30-day overlap window ────────► │
  │                │                     │                     │
  │                │     Both credentials work                 │
  │                │     Update anytime                        │
  │                │                     │                     │
  │                │                     │  Old expires        │
  │                                      New credentials active
                                         │◄───────────────────►

Key dates:

Day 150: You get email with new credentials

Days 150-180: Both old and new credentials work (update anytime)

Day 180: Old credentials expire

Day 210: New credentials expire (next rotation starts Day 180)

How It Works

Step	What Happens	Your Action
1. Email	You receive rotation notification 30 days before expiration	Check email
2. Retrieve	Get new credentials via secure endpoint	Run curl command
3. Update	Change credentials in your app config	Update & deploy
4. Test	Make one API call with new credentials	Call `/token` endpoint
5. Done	New credentials auto-activate, old ones retire	Nothing — automatic!

Zero downtime: Old credentials work until you use the new ones. Update whenever convenient within 30 days.

Retrieve New Credentials

Endpoint: GET /api/credentials/new

Authentication: HTTP Basic Auth with your current active credentials

Curl example:

Response (200 OK):

{
  "clientId": "fa6695e5092d4e979a111335d8c8fc54",
  "clientSecret": "newSecretValue64CharsLong...",
  "credentialId": "8a2f4c1d-3e5b-4a6c-9d7e-1f2a3b4c5d6e",
  "validFrom": "2026-06-01T00:00:00Z",
  "validUntil": "2026-12-01T00:00:00Z",
  "isActive": false,
  "message": "Update your application with the new clientSecret. It will activate automatically on first successful authentication."
}

Response fields:

clientSecret - Your new secret (save securely)

validFrom / validUntil - New credential validity window

isActive: false - Not active yet (activates when you use it)

Status Codes

Code	Meaning	What To Do
200	New credentials retrieved successfully	Update your config
404	No new credential found (rotation not started yet)	Wait for email notification
410	New credential already activated	You're already using it
429	Too many requests (rate limited)	Wait 1 hour, try again

Activation Process

Automatic activation on first auth:

1. You call POST /authentication/token with new credentials
2. Token returned immediately ✅
3. In background: new credential activates, old one retires
4. Next auth must use new credentials

During 30-day overlap:

✅ Old credentials work

✅ New credentials work

✅ Switch anytime

After activation:

❌ Old credentials stop working

✅ Only new credentials work

Pro tip: Test new credentials in staging before updating production.

Common Questions

"When should I update?"

Anytime within the 30-day window. We recommend within first 2 weeks to avoid last-minute issues.

"What happens if I don't update?"

Your old credentials expire. Your integration stops working. Update before expiration date in the email.

"Can I get the new secret multiple times?"

Yes, until you activate it. After first successful auth with new credentials, endpoint returns 410 Gone.

"Will my integration stop during rotation?"

No. Both credentials work during the overlap. Zero downtime.

"I lost the new secret before updating"

Contact integration-support@srsdistribution.com for manual regeneration.

Testing

Before deploying to production:

Get new credentials:

Test in staging:

Verify token works:

Deploy to production when ready

Troubleshooting

"404 Not Found when calling /api/credentials/new"

You don't have new credentials yet

Rotation starts 30 days before expiration

Check your email for notification

"401 Unauthorized"

Your current credentials are wrong

Use your active credentials to retrieve the new ones

Check CLIENT_ID and CURRENT_SECRET

"410 Gone"

New credentials already activated

You're already using them

No action needed

"429 Too Many Requests"

Rate limit: 10 requests per hour

Wait 1 hour before retrying

You only need to call once

Security Best Practices

DO:

✅ Store secrets in environment variables or secrets manager

✅ Use HTTPS only

✅ Test in staging first

✅ Update within 30-day window

DON'T:

❌ Commit secrets to source control

❌ Share secrets in Slack/email

❌ Hard-code secrets in application code

❌ Wait until last day to update

Email Notifications

You'll receive emails at these times:

When	Subject	Action
30 days before expiry	New credentials ready	Retrieve & update soon
14 days before expiry	Reminder	Update if you haven't
7 days before expiry	Urgent reminder	Update now
After activation	Rotation complete	Nothing — confirmation only

Next Steps

Watch for rotation email

Run curl command to get new credentials

Update staging environment

Test thoroughly

Deploy to production

Done ✅

Questions? Email integration-support@srsdistribution.com

Related: Authentication Guide | Order Flow

Credential Rotation#

Quick Facts#

Rotation Timeline#

How It Works#

Retrieve New Credentials#

Status Codes#

Activation Process#

Common Questions#

"When should I update?"#

"What happens if I don't update?"#

"Can I get the new secret multiple times?"#

"Will my integration stop during rotation?"#

"I lost the new secret before updating"#

Testing#

Troubleshooting#

"404 Not Found when calling /api/credentials/new"#

"401 Unauthorized"#

"410 Gone"#

"429 Too Many Requests"#

Security Best Practices#

Email Notifications#

Next Steps#

Credential Rotation

Quick Facts

Rotation Timeline

How It Works

Retrieve New Credentials

Status Codes

Activation Process

Common Questions

"When should I update?"

"What happens if I don't update?"

"Can I get the new secret multiple times?"

"Will my integration stop during rotation?"

"I lost the new secret before updating"

Testing

Troubleshooting

"404 Not Found when calling /api/credentials/new"

"401 Unauthorized"

"410 Gone"

"429 Too Many Requests"

Security Best Practices

Email Notifications

Next Steps