Zoom Oauth

OAuth 5-Minute Preflight Runbook

Use this before deep debugging. It catches common OAuth failures fast.

Skill Doc Standard Note

• Agent-skill standard entrypoint is SKILL.md.

• This runbook is an operational convention (recommended), not a required skill file.

• SKILL.md is also a navigation convention for larger skill docs.

1) Confirm You Chose the Right Flow

• S2S (account_credentials) for backend automation on your own account.

• User OAuth (authorization_code) for acting on behalf of users.

• Device flow for browserless devices.

• Client credentials for chatbot-only scenarios.

Wrong flow choice causes scope and token errors later.

2) Confirm Endpoint Split

• Authorize URL: https://zoom.us/oauth/authorize

• Token URL: https://zoom.us/oauth/token

If token requests return 404/HTML, verify you are not calling /oauth/token.

3) Confirm Redirect URI Exact Match

• redirect_uri in token exchange must exactly match Marketplace config.

• Match scheme, host, path, and trailing slash.

State Parameter Guardrail

• Always generate and verify state for user OAuth flows.

• Expire state quickly and consume once.

• If callback has code but state is missing/invalid, reject and restart auth.

4) Confirm Scope and App Type Alignment

• Verify required scopes are added to app.

• Re-authorize after scope changes.

• Ensure app type supports requested behavior.

5) Confirm Token Lifecycle Handling

• Access token expires ~1 hour.

• Store latest refresh token after each refresh.

• Handle refresh failure with re-auth fallback.

Refresh Rotation Reminder

• Treat refresh tokens as rotating credentials.

• Persist new refresh token returned by refresh response.

• Using stale refresh tokens causes intermittent auth failures later.

6) Quick Probes

• Token endpoint returns JSON with access_token.

• API call to /v2/users/me succeeds with bearer token.

• Redirect callback receives code and valid state.

Copy/Paste Validation Commands

Use these to verify OAuth plumbing in under a minute.

# 1) S2S token request
curl -X POST "https://zoom.us/oauth/token" \
  -H "Authorization: Basic $(printf '%s:%s' "$ZOOM_CLIENT_ID" "$ZOOM_CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=account_credentials&account_id=$ZOOM_ACCOUNT_ID"

# 2) User auth-code exchange
curl -X POST "https://zoom.us/oauth/token" \
  -H "Authorization: Basic $(printf '%s:%s' "$ZOOM_CLIENT_ID" "$ZOOM_CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=$ZOOM_AUTH_CODE&redirect_uri=$ZOOM_REDIRECT_URI"

# 3) Token health check
curl -X GET "https://api.zoom.us/v2/users/me" \
  -H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"

7) Fast Decision Tree

• 4709 redirect mismatch -> fix exact redirect URI.

• 4702/4704 invalid client -> wrong client credentials or app.

• 4733/4734 code errors -> auth code expired/invalid, restart consent flow.

• Scopes missing -> add scopes + re-authorize.

8) Flow-to-App-Type Guardrail

• If using account_credentials, app must support S2S flow.

• If using authorization_code, app and redirect configuration must support user consent.

• If auth appears valid but API fails, verify app type, scope level, and account ownership assumptions.