跳转到主要内容
OAuth 应用允许第三方应用代表用户访问 Teable。本指南介绍如何创建和配置 OAuth 应用、实现 OAuth 2.0 授权流程，以及使用访问令牌与 Teable API 交互。

​
创建 OAuth 应用

  1. 进入 Teable 账户的设置 > OAuth 应用页面。
  2. 点击新增 OAuth 应用创建新应用。
  3. 填写必要信息：
    • OAuth 应用名称：应用的描述性名称
    • 主页 URL：应用网站的完整 URL
    • 回调 URL：用户授权后重定向的 URL
    • 权限范围：应用所需的权限
  4. 创建应用后，生成客户端密钥。请务必复制并安全保存——您将无法再次查看。
您将获得一个客户端 ID，并需要生成客户端密钥。请妥善保管这些凭据，切勿在客户端代码中暴露。

​
可用权限范围

权限范围定义了 OAuth 应用可以执行的操作。可用范围按资源类型组织：
资源权限范围
表格table|create, table|delete, table|export, table|import, table|read, table|update, table|trash_read, table|trash_update, table|trash_reset
视图view|create, view|delete, view|read, view|update
字段field|create, field|delete, field|read, field|update
记录record|comment, record|create, record|delete, record|read, record|update
自动化automation|create, automation|delete, automation|read, automation|update
用户user|email_read
只请求应用实际需要的权限范围。用户在授权时会看到请求的权限列表。

​
OAuth 2.0 授权流程

Teable 实现了标准的 OAuth 2.0 授权码流程：

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

使用应用参数将用户引导到授权端点： 
GET https://app.teable.cn/api/oauth/authorize
查询参数：
参数是否必需描述
response_type是必须为 code
client_id是您的 OAuth 应用的客户端 ID
redirect_uri否必须与注册的回调 URL 之一匹配。如省略，将使用第一个注册的回调 URL
scope否以空格分隔的权限范围列表。如省略，使用 OAuth 应用中配置的范围
state否用于防止 CSRF 攻击的随机字符串。将在回调中返回
示例： 
https://app.teable.cn/api/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=table|read%20record|read&state=random_state_string

​
步骤 2：用户授权

用户将看到授权页面，显示：
  • 您的应用名称和标志
  • 请求的权限（范围）
  • 批准或拒绝选项
如果用户之前已授权过您的应用（默认 7 天内有效），将直接重定向而不再显示授权页面。

​
步骤 3：处理回调

用户批准（或拒绝）后，Teable 会重定向到您的回调 URL： 成功时： 
https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=random_state_string
拒绝时： 
https://yourapp.com/callback?error=access_denied&state=random_state_string

​
步骤 4：用授权码换取令牌

用授权码换取访问令牌和刷新令牌： 
POST https://app.teable.cn/api/oauth/access_token
Content-Type: application/x-www-form-urlencoded
请求体：
参数是否必需描述
grant_type是必须为 authorization_code
code是收到的授权码
client_id是您的 OAuth 应用的客户端 ID
client_secret是您的 OAuth 应用的客户端密钥
redirect_uri否必须与授权时使用的 redirect_uri 匹配
请求示例： 
curl -X POST https://app.teable.cn/api/oauth/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"
响应： 
{
  "token_type": "Bearer",
  "access_token": "teable_xxxxxxxxxxxx",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 600,
  "refresh_expires_in": 2592000,
  "scopes": ["table|read", "record|read"]
}
字段描述
token_type始终为 Bearer
access_token用于 API 请求的令牌
refresh_token用于获取新访问令牌的令牌
expires_in访问令牌有效期（秒）（默认：600 = 10 分钟）
refresh_expires_in刷新令牌有效期（秒）（默认：2592000 = 30 天）
scopes已授权的权限范围数组

​
使用访问令牌

在 API 请求的 Authorization 头中包含访问令牌： 
curl https://app.teable.cn/api/table/TABLE_ID/record \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
刷新访问令牌

当访问令牌过期时，使用刷新令牌获取新的访问令牌： 
POST https://app.teable.cn/api/oauth/access_token
Content-Type: application/x-www-form-urlencoded
请求体：
参数是否必需描述
grant_type是必须为 refresh_token
refresh_token是当前的刷新令牌
client_id是您的 OAuth 应用的客户端 ID
client_secret是您的 OAuth 应用的客户端密钥
请求示例： 
curl -X POST https://app.teable.cn/api/oauth/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
刷新后，之前的刷新令牌将失效。请务必保存响应中的新刷新令牌。

​
撤销访问权限

​
OAuth 应用所有者

要撤销为特定客户端发放的所有令牌，使用撤销端点： 
POST https://app.teable.cn/api/oauth/client/{clientId}/revoke-token
这将使该 OAuth 应用的所有访问令牌和刷新令牌失效。

​
用户

用户可以通过已授权应用设置页面撤销访问权限。

​
应用程序

应用程序可以撤销自己的访问权限： 
GET https://app.teable.cn/api/oauth/client/{clientId}/revoke-token
Authorization: Bearer YOUR_ACCESS_TOKEN

​
令牌过期时间

令牌类型默认过期时间可通过环境变量配置
授权码5 分钟BACKEND_OAUTH_CODE_EXPIRE_IN
访问令牌10 分钟BACKEND_OAUTH_ACCESS_TOKEN_EXPIRE_IN
刷新令牌30 天BACKEND_OAUTH_REFRESH_TOKEN_EXPIRE_IN
授权记忆期7 天BACKEND_OAUTH_AUTHORIZED_EXPIRE_IN

​
错误处理

常见错误响应：
错误描述
invalid_client无效的客户端 ID 或客户端密钥
invalid_grant授权码已过期或已使用
invalid_scope请求的权限范围不被该 OAuth 应用允许
access_denied用户拒绝了授权请求
redirect_uri_mismatch重定向 URI 与注册的 URL 不匹配

​
最佳实践

  1. 安全存储密钥：切勿在客户端代码中暴露您的客户端密钥
  2. 使用 state 参数：始终包含随机的 state 参数以防止 CSRF 攻击
  3. 请求最小权限范围：只请求应用实际需要的权限
  4. 处理令牌刷新：在令牌过期前实现自动刷新
  5. 安全存储令牌：将访问令牌和刷新令牌安全地存储在服务器端