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.

3.1 KiB Raw Permalink Blame History