How to rotate your tenant auth secret

Before you start

Rotating your auth secret invalidates the previous one immediately. Identify all services that depend on the secret before you rotate. After rotating, update them with the new value immediately.

A valid M2M access token (see How to authenticate)
Your tenant_slug, the tenant DNS slug used in the API host and path (for example, demo-retail)
Required scopes: read:tenant_auth_secret to retrieve the current secret and update:tenant_auth_secret to rotate it

Retrieve your current auth secret

Confirm your existing secret is still active:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/tenants/auth-secret' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Rotate the secret

curl -X POST 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/tenants/rotate-auth-secret' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
  "data": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_NEW_SECRET"
  }
}

Copy the client_secret value. The previous secret is immediately invalidated.

Update your integration

Replace the old secret in your app configuration with the new value returned in the response. Redeploy or restart any services that cache the secret.

Verify the new secret works

Request a fresh access token using the new secret:

curl -X POST 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_NEW_SECRET'

A 200 response confirms the rotation succeeded.

If it's not working

Symptom	Action
`403` on retrieve endpoint	Confirm your token has `read:tenant_auth_secret` permission
`403` on rotate endpoint	Confirm your token has `update:tenant_auth_secret` permission
`401` after rotation	You are still using the old secret; update your configuration