Zoom Oauth

Scopes Architecture

Zoom OAuth uses scopes to limit API access. Understanding Classic vs Granular scopes is critical.

Scope Types

Classic Scopes

Format

{resource}:{action}:{level}

Examples:

• meeting:read - Read user's own meetings

• meeting:write:admin - Create/update meetings for all account users

• recording:read:master - Read recordings across all sub-accounts

Scope Levels

Common Classic Scopes

meeting:read               # View own meetings
meeting:write              # Create/edit own meetings
meeting:write:admin        # Manage all account meetings

user:read                  # View own profile
user:write:admin           # Manage account users

recording:read             # View own recordings
recording:write:admin      # Manage account recordings

webinar:read               # View own webinars
webinar:write:admin        # Manage account webinars

imchat:bot                 # Team Chat bot access

Granular Scopes

Format

{service}:{action}:{data_claim}:{access_level}

Examples:

• meeting:read:meeting:user - Read user's own meetings

• meeting:write:invite_links:admin - Create invite links for account

• recording:delete:recording_file:admin - Delete recording files account-wide

Components

1. service: API category (meeting, user, recording, etc.)

2. action: Operation (read, write, delete, etc.)

3. data_claim: Specific data type (meeting, participant, invite_links, etc.)

4. access_level: Scope of access (user, admin, account, etc.)

Access Levels (Granular)

Classic vs Granular Comparison

Meetings Scope Example

Why Granular Scopes Exist

Classic scopes are broad:

• meeting:write:admin grants ALL meeting write permissions account-wide

• Includes create, update, delete, settings, etc.

Granular scopes are specific:

• meeting:write:meeting:admin - Only create/update meetings

• meeting:delete:meeting:admin - Only delete meetings

• meeting:write:settings:admin - Only update settings

Principle of Least Privilege: Request only the granular scopes you need.

Choosing Between Classic and Granular

Use Classic When:

• You need broad access (e.g., full meeting management)

• Simpler scope management preferred

• Legacy app migration

Use Granular When:

• You need specific permissions only

• Implementing principle of least privilege

• Building security-sensitive apps

Can You Mix?

✅ Yes, you can request both Classic and Granular scopes in the same app.

scope=meeting:read user:write:admin meeting:write:invite_links:admin

Requesting Scopes

During App Creation (S2S OAuth, Chatbot)

Scopes are configured in Zoom Marketplace:

1. Go to your app in https://marketplace.zoom.us

2. Click "Scopes" tab

3. Select required scopes (Classic or Granular)

4. Click "Continue"

Token will include all configured scopes.

During Authorization (User OAuth, Device Flow)

Scopes are requested in authorization URL:

const authURL = new URL('https://zoom.us/oauth/authorize');
authURL.searchParams.set('response_type', 'code');
authURL.searchParams.set('client_id', CLIENT_ID);
authURL.searchParams.set('redirect_uri', REDIRECT_URI);

// Request specific scopes (space-separated)
authURL.searchParams.set('scope', 'meeting:read user:read recording:read');

// User sees consent screen listing these scopes

Scope Consent Screen

When user authorizes your app, they see:

[Your App Name] wants to:

✓ View your meetings (meeting:read)
✓ View your profile (user:read)
✓ View your recordings (recording:read)

[Deny] [Authorize]

Scope Errors

Error 4711: Scope Mismatch

Cause: Token's scopes don't include required scope for API endpoint.

Example:

// Token has: meeting:read
// API requires: meeting:write
await axios.post('https://api.zoom.us/v2/users/me/meetings', {...}, {
  headers: { Authorization: `Bearer ${token}` }
});
// Error 4711: Insufficient scope

Solution:

1. Add required scope in Zoom Marketplace (S2S/Chatbot)

2. OR request scope in authorization URL (User/Device)

3. Re-authorize user to grant new scopes

Checking Token Scopes

Decode Access Token Scopes

// S2S OAuth: scopes returned in token response
const { access_token, scope } = tokenResponse.data;
console.log('Scopes:', scope); // "meeting:read user:read recording:write"

// User OAuth: scopes returned during token exchange
const { access_token, scope } = tokenResponse.data;
console.log('Granted scopes:', scope.split(' ')); // ['meeting:read', 'user:read', ...]

API to Get Token Scopes

curl -H "Authorization: Bearer {access_token}" \
  https://zoom.us/oauth/token

Best Practices

1. Request Minimum Scopes Needed

// ❌ AVOID: Requesting broad admin access when not needed
scope: "meeting:write:admin user:write:admin recording:write:admin"

// ✅ PREFER: Request only what you need
scope: "meeting:read user:read"

2. Use Granular Scopes for Specific Operations

// ❌ Classic (broad)
scope: "meeting:write:admin" // Includes create, update, delete, settings, etc.

// ✅ Granular (specific)
scope: "meeting:write:meeting:admin" // Only create/update meetings

3. Document Required Scopes

/**
 * Create a meeting for a user
 * Required scope: meeting:write:admin (Classic) or meeting:write:meeting:admin (Granular)
 */
async function createMeeting(userId, meetingData) {
  // ...
}

Reference Documentation

• Classic Scopes → ../references/classic-scopes.md

• Granular Scopes → ../references/granular-scopes.md

• Scope Errors → ../troubleshooting/scope-issues.md