Skip to content

Concept map· 6 connected terms

Token Rotation

Also called: Credential rotation · Secret rotation · API key rotation

In one line
Replacing access tokens, app secrets and API keys on a schedule or after exposure, with an overlap so services switch over without downtime.

Reviewed

What is token rotation?

Token rotation is the routine replacement of a credential — an access token, API key, app secret, signing key or certificate — with a new value, followed by revocation of the old one. It happens on a schedule, so a credential's useful life is limited even if it leaks unnoticed, and on demand, when a token turns up in a repository, a log or a departing contractor's laptop.

The hard part is doing it without an outage. Rotation works when both credentials are valid for a short overlap: the new token is created, rolled out to every service that uses it and confirmed in live traffic, and only then is the old one revoked. Revoking first, or rotating something that four services read from four places, is how rotation causes downtime — which is why it pairs with secrets management, so each credential lives in one store and services pick up the new value automatically.

On the WhatsApp Business Platform the main credentials are the system user access token that authorises Graph API calls and the app secret that keys X-Hub-Signature-256 webhook signatures and appsecret_proof. When you generate a system user token in Business Settings you can choose whether it expires, and the debug_token endpoint reports expires_at (0 means no expiry). Resetting the app secret in the App Dashboard issues a new one, and Meta signs webhooks with it from then on. Token rotation governs how credentials change over time; secrets management governs where they live.

Key takeaways

  • Token rotation replaces a credential with a new one and retires the old, on a schedule or straight after a suspected leak.
  • Zero-downtime rotation follows one order: create the new credential, deploy it, verify traffic, then revoke the old one.
  • Meta system user tokens can be generated with an expiry; the debug_token endpoint reports expires_at so you can rotate in time.
  • Resetting an app secret changes the key behind X-Hub-Signature-256, so webhook verifiers should briefly accept both secrets.
  • Token rotation is the change process; secrets management is where credentials are stored and who can read them.

Walk through a zero-downtime rotation

7 / 7

TEvent 7 of 7

Old expiry passes quietly

The date that would have been an outage is a non-event.

An illustrative system user token rotation, from the expiry alert to revocation. Scrub along the timeline to see why the overlap — not the new token — is what prevents an outage.

Event 7 of 7: T — Old expiry passes quietly. The date that would have been an outage is a non-event.

Why does token rotation matter?

A token that never changes is a permanent key to your WhatsApp account: anyone who ever copied it — a contractor, a leaked CI log, an old backup — can send messages in your name and run up charges indefinitely. Regular rotation caps that exposure, and a practised rotation turns a leak from a crisis into a twenty-minute runbook. Teams that have never rotated usually discover, at the worst moment, that nobody knows every place the token is used.

How does token rotation work?

  1. Create the new credential

    Generate a new system user token with only the permissions it needs, such as whatsapp_business_messaging and whatsapp_business_management, alongside the existing one — or a new API key next to the old.

  2. Store it and roll it out

    Write the new value to the secret store as a new version. Services that cache secrets pick it up on their next refresh; anything else is redeployed.

  3. Verify live traffic

    Confirm successful Graph API calls with the new token and check that nothing still authenticates with the old one. Logs that record which secret version was used make this a query, not a guess.

  4. Revoke the old credential

    Revoke the old token in Business Settings or delete the old API key. If something breaks now, you have found a hidden consumer — fix it and add it to the inventory.

  5. Record and schedule

    Log who rotated what and when, and set the next rotation date well before the new token's expiry.

Token rotation in code

# Inspect a token: is it valid, which scopes, when does it expire?
curl -G "https://graph.facebook.com/v26.0/debug_token" \
  -H "Authorization: Bearer {APP_OR_ADMIN_TOKEN}" \
  --data-urlencode "input_token={TOKEN_TO_CHECK}"
 
# Trimmed response
# {
#   "data": {
#     "app_id": "{APP_ID}",
#     "is_valid": true,
#     "issued_at": 1792368000,
#     "expires_at": 1797552000,      <- 0 means the token does not expire
#     "scopes": ["whatsapp_business_management", "whatsapp_business_messaging"],
#     "user_id": "{SYSTEM_USER_ID}"
#   }
# }

Run it daily from a scheduled job and alert when expires_at is less than 14 days away.

Key facts at a glance

Token rotation: key facts and limits

Rotation order
Create → deploy → verify → revoke
Expiry check
GET /debug_token → expires_at (0 = no expiry)
System user token expiry
Chosen when the token is generated
App secret reset
New key for X-Hub-Signature-256 and appsecret_proof
Rotate immediately when
A token is exposed or someone with access leaves
Revoked or expired token
Graph API error 190

Example: Rotating after an agency exit

A Bengaluru food-delivery brand ends its contract with a marketing agency that had a copy of the WhatsApp access token. The engineering team generates a new system user token with the same two WhatsApp permissions and an expiry, writes it to the secret store as a new version and watches the sending service pick it up within five minutes. After a full day with no calls on the old token — including the nightly campaign job — they revoke it. The agency's forgotten scheduler starts failing with error 190, which is exactly the point.

Common wrong turns

Common mistakes with token rotation

  • Revoking before rolling out

    Revoking the old token first guarantees an outage for every service not yet updated. Always overlap: new token live everywhere and verified, then revoke.

  • Hidden consumers

    A cron job, a staging server or a partner integration still using the old token breaks on revocation day. Keep an inventory per credential and watch for error 190 right after revoking.

  • Non-expiring tokens with no schedule

    A token without expiry is convenient and dangerous. If you must use one, put a rotation date in the team calendar and treat it as a deadline.

  • Forgetting webhooks when resetting the app secret

    After a reset, Meta signs webhooks with the new secret. A verifier holding only the old one rejects every event — accept both briefly, then remove the old.

Good practice

Best practices for token rotation

  • Rotate on a fixed rhythm, for example every 60–90 days, and after every staff or agency change.
  • Give each service or client its own token so one rotation does not touch everything.
  • Automate the expiry check with debug_token and alert at 14 days.
  • Rehearse a rotation in staging every quarter so the runbook stays accurate.

Token Rotation FAQs

How often should I rotate API tokens?+
Rotate on a schedule — commonly every 60 to 90 days — and immediately after any exposure or when someone with access leaves. Shorter lifetimes limit how long a leaked token stays useful.
Do Meta system user access tokens expire?+
They can. When you generate a system user token in Business Settings you choose whether it expires, and the debug_token endpoint shows its `expires_at`; a value of 0 means it does not expire.
How do I rotate a WhatsApp access token without downtime?+
Generate the new token while the old one still works, deploy it everywhere, confirm traffic has moved, then revoke the old token. The overlap is what prevents downtime.
What happens to webhooks when I reset my app secret?+
Meta starts signing webhooks with the new secret, so verifiers still holding the old one reject every event. Deploy code that accepts both secrets before the reset, then remove the old one.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms