zoom-oauth

Zoom OAuth

Zoom 认证与令牌生命周期行为的背景参考。请先使用 setup-zoom-oauth，然后再使用本 Skill 查看具体流程、Scope 和错误详情。

Zoom OAuth

Zoom API 的认证与授权。

📖 完整文档

有关全面指南、生产环境模式和故障排查，请参阅下方的集成索引部分。

快速导航：

• 5 分钟运行手册 - 在深入调试前进行预检
• OAuth 流程 - 应使用哪种流程以及各流程的工作方式
• 令牌生命周期 - 过期、刷新和撤销
• 生产环境示例 - Redis 缓存、MySQL 存储、自动刷新
• 故障排查 - 错误码 4700-4741

前提条件

• 已在 Marketplace 中创建 Zoom 应用
• Client ID 和 Client Secret
• 对于 S2S OAuth：Account ID

四种授权用例

用例	应用类型	Grant Type	行业名称
账户授权	Server-to-Server	account_credentials	Client Credentials Grant、M2M、Two-legged OAuth
用户授权	General	authorization_code	Authorization Code Grant、Three-legged OAuth
设备授权	General	urn:ietf:params:oauth:grant-type:device_code	Device Authorization Grant（RFC 8628）
客户端授权	General	client_credentials	Client Credentials Grant（限定于聊天机器人）

行业术语

术语	含义
Two-legged OAuth	不涉及用户（客户端 ↔ 服务器）
Three-legged OAuth	涉及用户（用户 ↔ 客户端 ↔ 服务器）
M2M	Machine-to-Machine（后端服务）
Public client	无法保守密钥（移动端、SPA）→ 使用 PKCE
Confidential client	可以保守密钥（后端服务器）
PKCE	Proof Key for Code Exchange（RFC 7636），读作 "pixy"

我应该使用哪种流程？

                              ┌─────────────────────┐
                              │  What are you       │
                              │  building?          │
                              └──────────┬──────────┘
                                         │
                    ┌────────────────────┼────────────────────┐
                    │                    │                    │
                    ▼                    ▼                    ▼
          ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
          │  Backend        │  │  App for other  │  │  Chatbot only   │
          │  automation     │  │  users/accounts │  │  (Team Chat)    │
          │  (your account) │  │                 │  │                 │
          └────────┬────────┘  └────────┬────────┘  └────────┬────────┘
                   │                    │                    │
                   ▼                    │                    ▼
          ┌─────────────────┐           │           ┌─────────────────┐
          │    ACCOUNT      │           │           │     CLIENT      │
          │   (S2S OAuth)   │           │           │   (Chatbot)     │
          └─────────────────┘           │           └─────────────────┘
                                        │
                                        ▼
                              ┌─────────────────────┐
                              │  Does device have   │
                              │  a browser?         │
                              └──────────┬──────────┘
                                         │
                         ┌───────────────┴───────────────┐
                         │ NO                         YES│
                         ▼                               ▼
          ┌─────────────────────────┐         ┌─────────────────┐
          │        DEVICE           │         │      USER       │
          │     (Device Flow)       │         │  (Auth Code)    │
          │                         │         │                 │
          │ Examples:               │         │ + PKCE if       │
          │ • Smart TV              │         │   public client │
          │ • Meeting SDK device    │         │                 │
          └─────────────────────────┘         └─────────────────┘

---

账户授权（Server-to-Server OAuth）

适用于无需用户交互的后端自动化场景。

请求访问令牌

POST https://zoom.us/oauth/token?grant_type=account_credentials&account_id={ACCOUNT_ID}

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

响应

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "user:read:user:admin",
  "api_url": "https://api.zoom.us"
}

刷新

访问令牌在 1 小时后过期。没有单独的刷新流程，只需请求新令牌即可。

---

用户授权（Authorization Code 流程）

适用于代表用户执行操作的应用。

步骤 1：将用户重定向至授权页面

https://zoom.us/oauth/authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}

使用 https://zoom.us/oauth/authorize 进行用户同意，使用 https://zoom.us/oauth/token 进行令牌交换。

可选参数：

参数	说明
state	CSRF 防护，在整个流程中保持状态
code_challenge	用于 PKCE（见下文）
code_challenge_method	S256 或 plain（默认：plain）

步骤 2：用户授权

• 用户登录并授予权限
• 携带授权码重定向至 redirect_uri：

  https://example.com/?code={AUTHORIZATION_CODE}
  

步骤 3：用授权码换取令牌

POST https://zoom.us/oauth/token?grant_type=authorization_code&code={CODE}&redirect_uri={REDIRECT_URI}

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

使用 PKCE 时： 添加 code_verifier 参数。

响应

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "refresh_token": "eyJ...",
  "expires_in": 3600,
  "scope": "user:read:user",
  "api_url": "https://api.zoom.us"
}

刷新令牌

POST https://zoom.us/oauth/token?grant_type=refresh_token&refresh_token={REFRESH_TOKEN}

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

• 访问令牌在 1 小时后过期
• 刷新令牌的有效期可能有所不同；对某些基于用户的流程，约 90 天较为常见。请将其视为可能变化的配置/行为，依赖运行时错误并以重新认证作为回退方案。
• 请始终使用最新的刷新令牌发起下一次请求
• 如果刷新令牌已过期，请将用户重定向至授权 URL 以重新开始流程

用户级与账户级应用

类型	可授权人员	Scope 访问范围
用户级	任何个人用户	仅限于其本人
账户级	具有管理员权限的用户	全账户访问（管理员 Scope）

---

设备授权（Device Flow）

适用于没有浏览器的设备（例如 Meeting SDK 应用）。

前提条件

在以下位置启用 "Use App on Device"：Features > Embed > Enable Meeting SDK

步骤 1：请求设备码

POST https://zoom.us/oauth/devicecode?client_id={CLIENT_ID}

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

Response

{
  "device_code": "DEVICE_CODE",
  "user_code": "abcd1234",
  "verification_uri": "https://zoom.us/oauth_device",
  "verification_uri_complete": "https://zoom.us/oauth/device/complete/{CODE}",
  "expires_in": 900,
  "interval": 5
}

Step 2: 用户授权

引导用户前往：

• verification_uri，并显示 user_code 以供手动输入，或
• verification_uri_complete（已预填用户代码）

用户登录并允许应用。

Step 3: 轮询获取令牌

以 interval（5 秒）的间隔轮询，直到用户完成授权：

POST https://zoom.us/oauth/token?grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code={DEVICE_CODE}

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

Response

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "refresh_token": "eyJ...",
  "expires_in": 3599,
  "scope": "user:read:user user:read:token",
  "api_url": "https://api.zoom.us"
}

轮询响应

Response	Meaning	Action
返回令牌	用户已授权	存储令牌，完成
error: authorization_pending	用户尚未授权	按间隔继续轮询
error: slow_down	轮询过于频繁	将间隔增加 5 秒
error: expired_token	设备代码已过期（15 分钟）	从 Step 1 重新开始流程
error: access_denied	用户拒绝授权	处理拒绝情况，不要重试

轮询实现

async function pollForToken(deviceCode, interval) {
  while (true) {
    await sleep(interval * 1000);
    
    try {
      const response = await axios.post(
        `https://zoom.us/oauth/token?grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=${deviceCode}`,
        null,
        { headers: { 'Authorization': `Basic ${credentials}` } }
      );
      return response.data; // Success - got tokens
    } catch (error) {
      const err = error.response?.data?.error;
      if (err === 'authorization_pending') continue;
      if (err === 'slow_down') { interval += 5; continue; }
      throw error; // expired_token or access_denied
    }
  }
}

Refresh

与用户授权相同。如果刷新令牌已过期，则从 Step 1 重新开始设备授权流程。

---

客户端授权（聊天机器人）

仅适用于聊天机器人消息操作。

请求令牌

POST https://zoom.us/oauth/token?grant_type=client_credentials

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

Response

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "imchat:bot",
  "api_url": "https://api.zoom.us"
}

Refresh

令牌有效期为 1 小时。没有刷新流程，直接请求新令牌即可。

---

使用访问令牌

调用 API

GET https://api.zoom.us/v2/users/me

Headers:
Authorization: Bearer {ACCESS_TOKEN}

Me Context

将 userID 替换为 me，即可指向令牌关联的用户：

Endpoint	Methods
/v2/users/me	GET, PATCH
/v2/users/me/token	GET
/v2/users/me/meetings	GET, POST

---

撤销访问令牌

适用于所有授权类型。

POST https://zoom.us/oauth/revoke?token={ACCESS_TOKEN}

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

Response

{
  "status": "success"
}

---

PKCE（Proof Key for Code Exchange）

适用于无法安全存储密钥的公共客户端（移动应用、SPA、桌面应用）。

何时使用 PKCE

Client Type	Use PKCE?	Why
移动应用	是	无法安全存储客户端密钥
单页应用（SPA）	是	JavaScript 对用户可见
桌面应用	是	二进制文件可被反编译
Meeting SDK（客户端侧）	是	运行在用户设备上
后端服务	可选	可以保管密钥，但 PKCE 能增加安全性

PKCE 工作原理

┌──────────┐                              ┌──────────┐                    ┌──────────┐
│  Client  │                              │   Zoom   │                    │   Zoom   │
│   App    │                              │  Auth    │                    │  Token   │
└────┬─────┘                              └────┬─────┘                    └────┬─────┘
     │                                         │                              │
     │ 1. Generate code_verifier (random)      │                              │
     │ 2. Create code_challenge = SHA256(verifier)                            │
     │                                         │                              │
     │ ─────── /authorize + code_challenge ──► │                              │
     │                                         │                              │
     │ ◄────── authorization_code ──────────── │                              │
     │                                         │                              │
     │ ─────────────── /token + code_verifier ─┼────────────────────────────► │
     │                                         │                              │
     │                                         │     Verify: SHA256(verifier) │
     │                                         │            == challenge      │
     │                                         │                              │
     │ ◄───────────────────────────────────────┼─────── access_token ──────── │
     │                                         │                              │

实现（Node.js）

const crypto = require('crypto');

function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
  return { verifier, challenge };
}

const pkce = generatePKCE();

const authUrl = `https://zoom.us/oauth/authorize?` +
  `response_type=code&` +
  `client_id=${CLIENT_ID}&` +
  `redirect_uri=${REDIRECT_URI}&` +
  `code_challenge=${pkce.challenge}&` +
  `code_challenge_method=S256`;

// Store pkce.verifier in session for callback

使用 PKCE 交换令牌

POST https://zoom.us/oauth/token?grant_type=authorization_code&code={CODE}&redirect_uri={REDIRECT_URI}&code_verifier={VERIFIER}

Headers:
Authorization: Basic {Base64(ClientID:ClientSecret)}

---

取消授权

当用户移除你的应用时，Zoom 会向你的取消授权通知端点 URL 发送 webhook。

Webhook 事件

{
  "event": "app_deauthorized",
  "event_ts": 1740439732278,
  "payload": {
    "account_id": "ACCOUNT_ID",
    "user_id": "USER_ID",
    "signature": "SIGNATURE",
    "deauthorization_time": "2019-06-17T13:52:28.632Z",
    "client_id": "CLIENT_ID"
  }
}

要求

• 收到此事件后删除所有关联的用户数据
• 验证 webhook 签名（使用 secret token，verification token 已于 2023 年 10 月弃用）
• 只有公共应用会收到取消授权 webhook（私有/开发应用不会）

---

预审批流程

部分 Zoom 账户要求 Marketplace 管理员预先审批后，用户才能授权应用。

• 用户可向其管理员申请预审批
• 账户级应用（管理员权限范围）需要相应的角色权限

---

Active Apps Notifier（AAN）

会议中的功能，用于显示可实时访问会议内容的应用。

• 显示图标和工具提示，包含应用信息、正在访问的内容类型以及批准该应用的账户
• 支持：Zoom 客户端 5.6.7 及以上版本，Meeting SDK 5.9.0 及以上版本

---

OAuth 权限范围

权限范围类型

Type	Description	For
经典权限范围	旧版权限范围（用户、管理员、主账户级别）	现有应用
细粒度权限范围	新的细粒度权限范围，部分支持可选项	新应用

经典权限范围

适用于此前创建的应用。分为三个级别：

• 用户级：访问单个用户的数据
• 管理员级：账户范围内的访问，需要管理员角色
• 主账户级：用于主-子账户设置，需要账户所有者

完整列表：https://developers.zoom.us/docs/integrations/oauth-scopes/

细粒度权限范围

适用于新应用。格式:<service>:<action>:<data_claim>:<access>

组成部分	取值
service	meeting、webinar、user、recording 等
action	read、write、update、delete
data_claim	数据类别(例如 participants、settings)
access	留空(用户)、admin、master

示例:meeting:read:list_meetings:admin

完整列表:https://developers.zoom.us/docs/integrations/oauth-scopes-granular/

可选权限范围

细粒度权限范围可以标记为 可选,用户可自行选择是否授予。

基础授权(使用构建流程的默认值):

https://zoom.us/oauth/authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}

高级授权(每次请求自定义权限范围):

https://zoom.us/oauth/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI}&scope={required_scopes}&optional_scope={optional_scopes}

包含先前已授予的权限范围:

https://zoom.us/oauth/authorize?...&include_granted_scopes&scope={additional_scopes}

从经典权限迁移到细粒度权限

1. Manage > 选择应用 > 编辑
2. Scope 页面 > Development 标签页 > 点击 Migrate
3. 检查自动分配的细粒度权限范围,移除不必要的,并标记为可选
4. 测试
5. Production 标签页 > 点击 Migrate

注意事项:

• 如果仅进行迁移或减少权限范围,则无需审核
• 现有用户令牌在重新授权前将继续使用经典权限范围值
• 新用户在迁移后将获得细粒度权限范围

---

常见错误代码

代码	消息	解决方案
4700	Token cannot be empty	检查 Authorization 请求头是否包含有效令牌
4702/4704	Invalid client	核对 Client ID 和 Client Secret
4705	Grant type not supported	使用:account_credentials、authorization_code、urn:ietf:params:oauth:grant-type:device_code 或 client_credentials
4706	Client ID or secret missing	将凭据添加到请求头或请求参数中
4709	Redirect URI mismatch	确保 redirect_uri 与应用配置完全一致(包括末尾斜杠)
4711	Refresh token invalid	令牌权限范围与客户端权限范围不匹配
4717	App has been disabled	联系 Zoom 支持
4733	Code is expired	授权码有效期为 5 分钟,请重新开始流程
4734	Invalid authorization code	重新生成授权码
4735	Owner of token does not exist	用户已从账户中移除,请重新授权
4741	Token has been revoked	使用最近一次授权获得的最新令牌

完整错误列表请参阅 references/oauth-errors.md。

---

快速参考

流程	Grant Type	令牌有效期	刷新
账户(S2S)	account_credentials	1 小时	请求新令牌
用户	authorization_code	1 小时	使用 refresh_token(有效期 90 天)
设备	urn:ietf:params:oauth:grant-type:device_code	1 小时	使用 refresh_token(有效期 90 天)
客户端(Chatbot)	client_credentials	1 小时	请求新令牌

---

演示指南

如果你构建了 OAuth 演示应用,请将其运行时基础 URL 记录在该演示项目自己的 README 或 .env.example 中,而不是记录在这个共享 skill 中。

资源

• OAuth 文档:https://developers.zoom.us/docs/integrations/oauth/
• S2S OAuth 文档:https://developers.zoom.us/docs/internal-apps/s2s-oauth/
• PKCE 博客:https://developers.zoom.us/blog/pcke-oauth-with-postman-rest-api/
• 经典权限范围:https://developers.zoom.us/docs/integrations/oauth-scopes/
• 细粒度权限范围:https://developers.zoom.us/docs/integrations/oauth-scopes-granular/

---

整合索引

本节迁移自 SKILL.md。

快速入门路径

如果你是 Zoom OAuth 新手，请按以下顺序操作：

1. 先运行预检查 → RUNBOOK.md

2. 选择你的 OAuth 流程 → concepts/oauth-flows.md

   • 4 种流程：S2S（后端）、User（SaaS）、Device（无浏览器）、Chatbot
   • 决策矩阵：哪种流程适合你的使用场景？

3. 了解令牌生命周期 → concepts/token-lifecycle.md

   • 重要：令牌如何过期、刷新和撤销
   • 常见误区：刷新令牌轮换

4. 实现你的流程 → 直接查看示例：

   • 后端自动化 → examples/s2s-oauth-redis.md
   • SaaS 应用 → examples/user-oauth-mysql.md
   • 移动端/SPA → examples/pkce-implementation.md
   • Device（电视/机顶盒）→ examples/device-flow.md

5. 修复重定向 URI 问题 → troubleshooting/redirect-uri-issues.md

   • 最常见的 OAuth 错误：重定向 URI 不匹配

6. 实现令牌刷新 → examples/token-refresh.md

   • 自动中间件模式
   • 处理刷新令牌轮换

7. 排查错误 → troubleshooting/common-errors.md

   • 错误码表（4700-4741 范围）
   • 快速诊断流程

---

文档结构

oauth/
├── SKILL.md                           # Main skill overview
├── SKILL.md                           # This file - navigation guide
│
├── concepts/                          # Core OAuth concepts
│   ├── oauth-flows.md                # 4 flows: S2S, User, Device, Chatbot
│   ├── token-lifecycle.md            # Expiration, refresh, revocation
│   ├── pkce.md                       # PKCE security for public clients
│   ├── scopes-architecture.md        # Classic vs Granular scopes
│   └── state-parameter.md            # CSRF protection with state
│
├── examples/                          # Complete working code
│   ├── s2s-oauth-basic.md            # S2S OAuth minimal example
│   ├── s2s-oauth-redis.md            # S2S OAuth with Redis caching (production)
│   ├── user-oauth-basic.md           # User OAuth minimal example
│   ├── user-oauth-mysql.md           # User OAuth with MySQL + encryption (production)
│   ├── device-flow.md                # Device authorization flow
│   ├── pkce-implementation.md        # PKCE for SPAs/mobile apps
│   └── token-refresh.md              # Auto-refresh middleware pattern
│
├── troubleshooting/                   # Problem solving guides
│   ├── common-errors.md              # Error codes 4700-4741
│   ├── redirect-uri-issues.md        # Most common OAuth error
│   ├── token-issues.md               # Expired, revoked, invalid tokens
│   └── scope-issues.md               # Scope mismatch errors
│
└── references/                        # Reference documentation
    ├── oauth-errors.md                # Complete error code reference
    ├── classic-scopes.md              # Classic scope reference
    └── granular-scopes.md             # Granular scope reference

---

按使用场景查找

我想自动化处理自己账户下的 Zoom 任务

1. OAuth 流程 - S2S OAuth 详解
2. S2S OAuth Redis - 基于 Redis 缓存的生产环境模式
3. 令牌生命周期 - 1 小时令牌，无刷新

我想为其他 Zoom 用户构建 SaaS 应用

1. OAuth 流程 - User OAuth 详解
2. User OAuth MySQL - 带加密的生产环境模式
3. 令牌刷新 - 自动刷新中间件
4. 重定向 URI 问题 - 修复最常见的错误

我想构建移动端或 SPA 应用

1. PKCE - 公共客户端为何必须使用 PKCE
2. PKCE 实现 - 完整代码示例
3. State 参数 - CSRF 防护

我想为没有浏览器的设备（电视、机顶盒）构建应用

1. OAuth 流程 - Device 流程详解
2. Device 流程示例 - 完整的轮询实现
3. 常见错误 - 设备相关错误

我正在构建 Team Chat 机器人

1. OAuth 流程 - Chatbot 流程详解
2. S2S OAuth Basic - 模式相似，授权类型不同
3. 权限范围架构 - Chatbot 专用权限范围

我遇到了重定向 URI 错误（4709）

1. 重定向 URI 问题 - 从这里开始！
2. 常见错误 - 错误详情
3. User OAuth Basic - 查看正确的实现方式

我遇到了令牌错误（4700-4741）

1. 令牌问题 - 诊断流程
2. 令牌生命周期 - 了解过期机制
3. 令牌刷新 - 实现自动刷新
4. 常见错误 - 错误码表

我遇到了范围错误（4711）

1. 范围问题 - 不匹配的原因
2. 范围架构 - 经典范围与细粒度范围
3. 经典范围 - 完整范围参考
4. 细粒度范围 - 细粒度范围参考

我需要刷新令牌

1. 令牌生命周期 - 何时刷新
2. 令牌刷新 - 中间件模式
3. 令牌问题 - 常见错误

我想了解经典范围与细粒度范围的区别

1. 范围架构 - 完整对比
2. 经典范围 - resource:level 格式
3. 细粒度范围 - service:action:data_claim:access 格式

我需要保护我的 OAuth 实现

1. PKCE - 公共客户端安全
2. State 参数 - CSRF 防护
3. User OAuth MySQL - 静态令牌加密

我想从 JWT 应用迁移到 S2S OAuth

1. S2S OAuth Redis - 现代替代方案
2. 令牌生命周期 - 不同的令牌行为

注意：JWT 应用类型已于 2023 年 6 月弃用。请迁移到 S2S OAuth 以实现服务端到服务端的自动化。

---

最关键的文档

1. OAuth 流程（决策文档）

concepts/oauth-flows.md

了解应使用这 4 种流程中的哪一种：

• S2S OAuth：后端自动化（使用您自己的账户）
• User OAuth：SaaS 应用（用户授权您）
• Device Flow：没有浏览器的设备
• Chatbot：仅适用于 Team Chat 机器人

2. 令牌生命周期（最常见的问题）

concepts/token-lifecycle.md

99% 的 OAuth 问题源于对以下内容的误解：

• 令牌过期（所有流程均为 1 小时）
• 刷新令牌轮换（必须保存新的刷新令牌）
• 撤销行为（会使所有令牌失效）

3. 重定向 URI 问题（最常见的错误）

troubleshooting/redirect-uri-issues.md

错误 4709（"Redirect URI mismatch"）是 OAuth 的头号错误。 必须完全一致（包括末尾斜杠、http 与 https）。

---

主要经验

关键要点：

1. 刷新令牌轮换

   • 每次刷新都会返回一个新的刷新令牌
   • 旧的刷新令牌随即失效
   • 未能保存新令牌会导致 4735 错误
   • 参见：令牌刷新

2. S2S OAuth 使用 Redis，用户 OAuth 使用数据库

   • S2S：整个账户共用一个令牌 → Redis（临时存储）
   • 用户：每个用户独立的令牌 → 数据库（持久存储）
   • 参见：S2S OAuth Redis 与 用户 OAuth MySQL

3. 重定向 URI 必须完全匹配

   • 末尾斜杠有影响：/callback ≠ /callback/
   • 协议有影响：http:// ≠ https://
   • 端口有影响：:3000 ≠ :3001
   • 参见：重定向 URI 问题

4. 公共客户端必须使用 PKCE

   • 移动应用无法保管密钥
   • 单页应用（SPA）无法保管密钥
   • PKCE 可防止授权码被截获
   • 参见：PKCE

5. State 参数用于防止 CSRF

   • 在重定向前生成随机的 state
   • 将其存储在会话中
   • 在回调时进行校验
   • 参见：State 参数

6. 令牌存储必须加密

   • 切勿以明文形式存储令牌
   • 至少使用 AES-256
   • 参见：用户 OAuth MySQL

7. JWT 应用类型已于 2023 年 6 月弃用

   • 无法再创建新的 JWT 应用
   • 现有应用仍可使用，但最终将被停用
   • 请迁移到 S2S OAuth 或用户 OAuth

8. 权限范围级别决定授权要求

   • 无后缀（用户级）：任何用户都可以授权
   • :admin：需要管理员角色
   • :master：需要账户所有者（多账户）
   • 参见：权限范围架构

9. 授权码 5 分钟后过期

   • 立即将授权码换取令牌
   • 不要缓存授权码
   • 参见：令牌生命周期

10. 设备流程需要轮询

    • 按 /devicecode 返回的间隔轮询（通常为 5 秒）
    • 处理 authorization_pending、slow_down 和 expired_token
    • 参见：设备流程

---

快速参考

"我应该使用哪种 OAuth 流程？"

→ OAuth 流程

"重定向 URI 不匹配错误（4709）"

→ 重定向 URI 问题

"令牌过期或无效"

→ 令牌问题

"刷新令牌无效（4735）"

→ 令牌刷新，必须保存新的刷新令牌

"权限范围不匹配错误（4711）"

→ 权限范围问题

"如何保护我的 OAuth 应用？"

→ PKCE + State 参数

"如何实现自动刷新？"

→ 令牌刷新

"经典权限范围与细粒度权限范围有什么区别？"

→ 权限范围架构

"每个错误代码分别代表什么？"

→ 常见错误

---

文档版本

基于 Zoom OAuth API v2（2024 年及以后）

已弃用： JWT 应用类型（2023 年 6 月）

---

祝编码愉快！

请记住：先阅读 OAuth 流程，了解哪种流程适合您的使用场景！

环境变量

• 参见 references/environment-variables.md，了解标准化的 .env 键名以及每个值的获取位置。