Calendar API for AI Agents: Recover From Credential Revocation Without Guessing Availability

Recover a hard meeting from credential revocation in eight steps

Use one sixty-minute customer review with an organizer, three required people, and one optional observer across Google and Microsoft. A required participant’s refresh token stops working after two slots were proposed. The organizer’s calendar remains writable, and the participant may reconnect or answer without calendar sync.

1. 1

   Persist typed meeting intent and credential dependencies

   Store meeting ID, revision, authenticated organizer, purpose, duration, bounded date range, booking deadline, IANA meeting zone, required and optional participants, approved substitutes, working-hour policy, organizer calendar, outreach authority, approval mode, and completion proof. For each calendar capability, record provider, account subject, tenant, granted permission class, encrypted credential reference, status, last successful refresh, and every meeting evidence object that depends on it.
   • Required and optional roles live in meeting state, never inside token metadata.
   • Workers receive credential references and typed commands rather than tokens or raw instructions.
   • One revoked grant can identify every availability snapshot, proposal, and pending write it affects.
2. 2

   Classify the failure before choosing recovery

   An expired access token normally enters a single-flight refresh path. A token-endpoint response indicating an invalid, expired, or revoked grant can enter reauth_required. Keep insufficient scope, tenant policy, account removal, provider outage, throttling, and malformed requests separate. One calendar API 401 is a signal to authenticate or refresh; it is not by itself permission to erase the credential or contact the participant.
   • Store provider reason, request correlation, detection time, token generation, and redacted account identity.
   • Bounded retries with jitter apply to transient transport or service failure, not a confirmed revoked grant.
   • Refresh work is deduplicated so ten blocked meetings do not race ten token exchanges.
3. 3

   Quarantine dependent evidence without deleting history

   Move the credential to reauth_required, stop new operations that need it, and mark affected free/busy snapshots access_lost. Revoke proposals whose required-participant proof no longer meets freshness policy. Preserve prior intervals and provider errors as audit evidence, but exclude them from new overlap. Missing access, stale evidence, and an empty busy response are three different states.
   • The participant is never modeled as free because the provider could not be read.
   • Unaffected Google, Microsoft, and conversational evidence remains usable under its own expiry.
   • Queued event writes re-check credential state, meeting revision, approval, and evidence before dispatch.
4. 4

   Select recovery by capability and participant role

   Build a recovery plan from the lost capability. A required person’s availability read can recover through provider re-consent or consent-safe bounded availability. An optional person can be omitted only under the organizer’s declared policy. Loss of the organizer’s event-write grant cannot be covered by somebody else’s availability reply; pause commit until the organizer reconnects or an already-authorized delegate calendar is selected.
   • Recovery never changes required attendance, organizer identity, or booking authority by inference.
   • Calendar sync remains optional for participant availability, not for a provider write that policy requires.
   • The organizer sees the affected person, capability, deadline risk, and available safe paths.
5. 5

   Run re-consent as a narrow, trusted operation

   Create one expiring re-consent task tied to credential subject, meeting revision, required permission class, redirect state, and return location. Send it only through an approved channel, explain the limited scheduling purpose, and route the user to the provider authorization surface. Keep authorization codes, refresh tokens, and access tokens out of prompts, analytics, URLs, participant messages, and model-visible traces.
   • A repeated recovery command returns the existing re-consent task instead of sending another request.
   • The callback verifies state, account subject, tenant, granted permissions, and current meeting ownership.
   • Denial, different-account consent, expired state, and admin-policy block each produce a typed next action.
6. 6

   Collect bounded availability when sync stays optional

   When outreach is authorized, ask only for windows inside the meeting date range. Include organizer, purpose at the approved disclosure level, duration, participant-local dates, named IANA zone, response deadline, correction path, reminder cap, and opt-out. Normalize the reply into versioned intervals with source, consent, received time, zone, confidence, and expiry. Ask one narrow clarification when the date or zone is ambiguous.
   • Silence blocks a required participant and never becomes an all-day opening.
   • A participant can decline calendar connection while still answering for this one meeting.
   • Re-consent and availability outreach share one recovery case so parallel paths cannot spam the person.
7. 7

   Restore evidence, recompute, and commit once

   After re-consent, perform a fresh bounded free/busy read and attach a new credential generation; do not resurrect old evidence merely because access returned. If conversational windows arrived first, keep them as separate evidence until expiry and apply declared source policy. Recompute required overlap, then optional attendance, working hours, buffers, and time-zone fairness. Bind approval to the resulting meeting revision, slot, attendees, evidence versions, and organizer calendar.
   • A later provider read can invalidate fallback-based proposals without rewriting the participant’s reply.
   • One booking idempotency key covers the approved meeting revision and slot.
   • If a write outcome is uncertain, recover access and reconcile provider state before another insert.
8. 8

   Verify completion and preserve the recovery trail

   Read back the canonical event with authorized access and verify start, end, zone, organizer, every required attendee, the optional-attendee decision, provider event identity, and invitation dispatch state. Close the recovery case only after that proof or an authorized terminal exception. Trace classification, quarantined evidence, user decisions, outreach, retries, recomputation, approval, write, reconciliation, and read-back with private content redacted.
   • A successful token exchange is recovery progress, not meeting completion.
   • Support can name the blocked capability, evidence age, recovery owner, deadline, and safe next action.
   • Metrics separate time to detect, time to re-consent, fallback completion, abandoned recovery, and verified booking.

Compare credential recovery by whether the meeting survives

Refreshing a token is one operation. Recovering a hard meeting means preserving roles, consent, evidence, deadlines, side effects, and proof while calendar authority changes.