Regenerate Business Key

Rotate your API authentication key for security compliance or after suspected compromise.

POST {{baseUrl}}/{{stage}}/external/businesses/{{businessID}}/regenerate-business-key

⚠️ WARNING: Regenerating immediately invalidates your old key. All API requests with the old key will fail. Plan accordingly.

When to Regenerate

✅ Yes:

Key exposed in logs/repos or unauthorized access detected

90-day rotation schedule (best practice)

Employee offboarding (key was shared)

System migration or compliance requirements

Request

Headers

Header	Value	Required
`Content-Type`	`application/json` or `/`	✅
`Accept`	`application/json` or `/`	✅

Path Parameters

Parameter	Type	Example	Description
`businessFirsId`	string (UUID v4)	`x6xxx24x-xxxx-xxxx-xxxx-xxxxxxfxxxx3`	Your business NRS ID

Request Body: None

Response

Success (200)

{
  "businessFirsId": "x6xxx24x-xxxx-xxxx-xxxx-xxxxxxfxxxx3",
  "businessKey": "BK_NEW_KEY_HERE",
  "responseCode": "00",
  "responseMessage": "Business key regenerated successfully"
}

Field	Description
`businessKey`	Your new key - Update all systems immediately
`responseCode`	`00` = success, `106` = invalid business ID

Errors

400 - Invalid Business ID

{
  "responseCode": "106",
  "responseMessage": "Business not found"
}

→ Verify businessFirsId format is correct UUID

429 - Rate Limit

{
  "responseCode": "106",
  "responseMessage": "You must wait 24 hours before regenerating another business key."
}

→ Limit: 1 per 24 hours, 10 per month. Contact support for emergency rotation.

Pre-Rotation Checklist

✅ Identify ALL systems using current key
✅ Schedule during low-traffic period
✅ Notify team members
✅ Test in staging first
✅ Set up monitoring for 401 errors

Rotation Steps

Generate new key

Update all systems

Environment variables

Secrets manager (AWS, Azure, etc.)

Restart services

Monitor for failures

Check for 401 Unauthorized errors

Verify new key working

Clean up

Remove old key from docs

Revoke shared credentials

Rate Limits

1 regeneration per 24 hours

10 regenerations per month

Exceeding limits triggers security review and 24-hour hold

Email notifications sent for:

Key regeneration

Failed attempts

Rate limit reached

Unauthorized regeneration attempts

FAQ

Q: How often should I rotate?
A: Every 90 days (30-60 days for strict compliance)

Q: Multiple active keys?
A: No. One key at a time. Old key immediately invalidated.

Q: Grace period for transition?
A: No. Old key fails immediately after regeneration.

Q: Can I revert to old key?
A: No. Regeneration is permanent.

Q: What about in-flight requests?
A: Requests using old key that are already processing will complete. New requests must use new key.

Regenerate Business Key

When to Regenerate#

Request#

Headers#

Path Parameters#

Response#

Success (200)#

Errors#

Pre-Rotation Checklist#

Rotation Steps#

Rate Limits#

FAQ#

Request

Responses

When to Regenerate

Request

Headers

Path Parameters

Response

Success (200)

Errors

Pre-Rotation Checklist

Rotation Steps

Rate Limits

FAQ