🚨 Microsoft Teams Error Guide: 'reauthorizationRequired' Graph Subscription Lifecycle — Renew and Reauthorize

Overview

Microsoft Graph delivers a lifecycle notification with lifecycleEvent: reauthorizationRequired when a Teams change subscription (for chat messages, channel messages, or presence) needs its authorization refreshed. If your service ignores it, Graph stops delivering change notifications and your bot silently goes deaf.

{
  "value": [{
    "subscriptionId": "8ee44408-0679-472a-bc02-4f6e0b3f3f2b",
    "subscriptionExpirationDateTime": "2026-07-10T18:23:45.0000000Z",
    "lifecycleEvent": "reauthorizationRequired",
    "resource": "teams/{team-id}/channels/{channel-id}/messages",
    "tenantId": "aaaabbbb-cccc-dddd-eeee-ffff00001111"
  }]
}

Symptoms

• Change notifications for Teams messages stop arriving even though the subscription hasn’t expired yet.
• Your lifecycleNotificationUrl receives reauthorizationRequired (and sometimes subscriptionRemoved) events you aren’t handling.
• Messages posted during a token/credential rotation window are never delivered.
• Subscriptions to /teams/.../messages or /chats/.../messages are especially affected because they carry short, frequently re-validated authorization.
• Renewal calls succeed but notifications remain dark until you also reauthorize.

Common Root Causes

• No lifecycle handler — the subscription was created without a lifecycleNotificationUrl, or the endpoint drops the event.
• Ignoring reauthorizationRequired — treating lifecycle events as informational instead of acting on them.
• Credential/consent change — an admin revoked or re-consented an app permission, invalidating the subscription’s cached authorization.
• Encryption certificate rotation — for rich (resource-data) notifications, the encryptionCertificate changed and Graph wants reauthorization.
• Clock/expiry drift — not renewing before subscriptionExpirationDateTime; Teams message subscriptions max out around 60 minutes and must be renewed aggressively.

Diagnostic Workflow

Confirm the subscription and its short expiry window:

curl -H "Authorization: Bearer ${GRAPH_TOKEN}" \
  "https://graph.microsoft.com/v1.0/subscriptions/${SUBSCRIPTION_ID}"

{
  "id": "8ee44408-0679-472a-bc02-4f6e0b3f3f2b",
  "resource": "teams/{team-id}/channels/{channel-id}/messages",
  "changeType": "created,updated",
  "notificationUrl": "https://ops.example.com/graph/notify",
  "lifecycleNotificationUrl": "https://ops.example.com/graph/lifecycle",
  "expirationDateTime": "2026-07-10T18:23:45Z"
}

Reauthorize the subscription in response to the lifecycle event:

curl -X POST -H "Authorization: Bearer ${GRAPH_TOKEN}" \
  "https://graph.microsoft.com/v1.0/subscriptions/${SUBSCRIPTION_ID}/reauthorize"

Then renew (extend) it, capping at the resource maximum:

curl -X PATCH -H "Authorization: Bearer ${GRAPH_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://graph.microsoft.com/v1.0/subscriptions/${SUBSCRIPTION_ID}" \
  -d '{ "expirationDateTime": "2026-07-10T19:20:00Z" }'

Your lifecycle endpoint must echo validationToken on setup and 202 the events fast:

POST /graph/lifecycle?validationToken=abc  ->  200 text/plain "abc"
POST /graph/lifecycle (event body)         ->  202 Accepted (then process async)

Example Root Cause Analysis

An on-call bot subscribed to teams/{team}/channels/{channel}/messages to mirror incident chatter into a war-room dashboard. It renewed subscriptions every 50 minutes but never implemented a lifecycleNotificationUrl. During a routine app-secret rotation, Graph emitted reauthorizationRequired — which went nowhere — and stopped delivering notifications. The renewal PATCH kept succeeding (extending expiry), so monitoring showed a “healthy” subscription while the war-room feed silently stalled for 40 minutes.

The fix: add a lifecycleNotificationUrl, and on reauthorizationRequired call POST /subscriptions/{id}/reauthorize immediately, followed by a PATCH renewal. They also added a watchdog that alerts if no notification arrives within 2x the expected interval, so a dark subscription pages a human instead of hiding behind a green expiry timestamp.

Prevention Best Practices

• Always create Teams message subscriptions with both notificationUrl and lifecycleNotificationUrl.
• Handle reauthorizationRequired by calling /reauthorize, then renew; handle subscriptionRemoved by recreating the subscription.
• Renew well before expiry — Teams message subscriptions are short-lived (~60 min); renew at ~50%.
• Persist subscription IDs and expiry, and run a reconciliation loop that recreates missing subscriptions.
• Add a liveness watchdog: alert when zero notifications arrive within an expected window, independent of expiry.
• Keep the encryption certificate current for resource-data notifications and reauthorize after rotation.

Quick Command Reference

# Reauthorize after a lifecycle event
curl -X POST -H "Authorization: Bearer $T" \
  https://graph.microsoft.com/v1.0/subscriptions/$SUB/reauthorize

# Renew (extend expiry)
curl -X PATCH -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  https://graph.microsoft.com/v1.0/subscriptions/$SUB \
  -d '{"expirationDateTime":"2026-07-10T19:20:00Z"}'

# List all subscriptions to find stale ones
curl -H "Authorization: Bearer $T" https://graph.microsoft.com/v1.0/subscriptions

# Recreate after subscriptionRemoved
curl -X POST -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  https://graph.microsoft.com/v1.0/subscriptions -d @subscription.json

Conclusion

reauthorizationRequired is Graph asking you to re-prove your subscription’s authorization before it keeps streaming Teams changes. Because a renewed subscription can still be un-reauthorized, expiry timestamps alone lie about health. Implement a lifecycle endpoint, reauthorize then renew on every event, recreate on removal, and add a delivery watchdog. That combination keeps your Teams message notifications flowing through credential rotations and consent changes instead of going silently dark.