Build Zoom Rest API App

REST API 5-Minute Preflight Runbook

Use this before deep debugging. It catches common Zoom REST API integration 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 Auth Flow and Endpoint

• Choose matching OAuth flow for use case (S2S/User/PKCE/Device).

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

Wrong flow or token endpoint causes immediate auth failures.

2) Confirm Scope and Account Context

• Verify token contains required scopes.

• For admin/account-level operations, verify app/account permissions.

• Re-authorize after scope changes.

3) Confirm ID Semantics

• Distinguish Meeting ID vs Meeting UUID.

• Apply required URL encoding (double-encoding for UUID where needed).

ID Sanity Rules

• Use numeric Meeting ID for many standard meeting operations.

• Use Meeting UUID for some past-instance/recording/report operations.

• If endpoint docs mention UUID and your value contains / or +, encode carefully.

If a resource "exists" in UI but API returns not found, ID type/encoding mismatch is a top cause.

4) Confirm Pagination and Rate Limits

• Handle next_page_token where applicable.

• Implement retry/backoff on 429 and transient 5xx.

Minimal Retry Policy

• 429 or 5xx: exponential backoff with jitter.

• Respect retry headers when provided.

• Put high-volume endpoints behind queue/batch workers.

5) Confirm Webhook-Driven Workflows

• If pipeline is event-driven, validate webhook signatures and retry behavior.

• Respond quickly and process asynchronously.

6) Quick Probes

• GET /v2/users/me succeeds with current token.

• Representative endpoint (e.g., list meetings) returns expected schema.

• Error payload includes actionable code/details (not HTML response).

Copy/Paste Validation Commands

# 1) Get S2S access token
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) Validate token can access account context
curl -X GET "https://api.zoom.us/v2/users/me" \
  -H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"

# 3) List meetings for current user (quick schema sanity)
curl -X GET "https://api.zoom.us/v2/users/me/meetings?page_size=30" \
  -H "Authorization: Bearer $ZOOM_ACCESS_TOKEN"

Expected: JSON responses with HTTP 200 (or clear JSON error codes), not HTML error pages.

7) Fast Decision Tree

• 401/invalid token -> wrong flow, expired token, or scope mismatch.

• 404-like behavior -> wrong endpoint path/version or wrong resource ID.

• 429 spikes -> missing backoff/queue strategy.

8) Common Integration Mixups

• REST join_url is a browser link, not a Meeting SDK join payload.

• REST API creates/manages Zoom resources; Meeting SDK and Video SDK are separate integration surfaces.

• If auth works but operation fails, check scope and resource ownership before endpoint debugging.