---
title: "资源、scope 与访问令牌"
description: "resource 指定令牌将发给哪个资源服务器；它不是 issuer、client ID 或登录开关。"
url: "https://auth.kai.com/docs/resources-and-tokens"
language: "zh-CN"
version: "Better Auth 1.7.1"
updated: "2026-09-22"
---

# 资源、scope 与访问令牌

resource 指定令牌将发给哪个资源服务器；它不是 issuer、client ID 或登录开关。

## 纯登录是否需要 resource

不需要。使用 `openid profile email` 完成 OIDC 登录时可省略 `resource`，当前实现通常返回 opaque access token。此令牌可用于 UserInfo；不要把它当作任意业务 API 的通行证。

如果调用 Exchange 等资源服务器，应使用该 API 正式约定的 identifier，例如 `https://exchange.kai.com`。不能为了获得 JWT 把目标换成 Auth issuer。JWT 的 `iss` 表示谁发放，`aud` 表示令牌给谁使用，这两个值承担不同职责。

## 请求资源的条件

当前 OAuth Provider 1.7.1 使用通用资源模型：

1. identifier 必须是有效的绝对 URI，不能含 fragment，且对应已注册、未禁用的资源。
2. 发起授权的客户端必须获准使用每个请求的资源。资源存在并不代表所有客户端自动有权使用。
3. 请求的 scope 必须先满足客户端范围，再与每个资源的 `allowedScopes` 依次取交集。未限制资源范围时不收缩；交集为空返回 `invalid_scope`。
4. 资源必须在用户批准的授权事务内；兑换或刷新不能擅自扩大目标。

未注册、已禁用或客户端未关联的资源会返回 `invalid_target`。

## 在控制台注册资源

进入组织 → 项目 → **API 资源**，创建资源并选择该项目内获准调用它的应用。可配置名称、HTTPS identifier、允许的 scope、访问令牌有效期（30–300 秒）及启用状态。identifier 全局唯一且创建后不可修改，不得含 fragment；当前可选范围为 `openid`、`profile`、`email`、`offline_access`，暂不支持自定义业务 scope。

资源属于项目。组织所有者、管理员、开发者及该项目管理员可以维护，普通项目成员仅查看。服务端与数据库共同限制资源只能授权给所属项目内的应用；客户端在授权请求里仍须传入所需的 `resource`，不会因为创建资源而自动改变授权请求。

移除应用关联、停用资源、缩小 scope 或改变令牌有效期会撤销受影响授权及其后续凭据。移出项目的应用会失去原项目的资源关联；删除项目也会删除其自助注册的资源。重新启用或重新关联不会复活已撤销凭据，需要重新授权。只修改显示名称不撤销授权。

上线前由平台登记的资源继续按原有授权关系运行；它们没有可信的项目归属时，不会被自动认领或硬编码绑定给某个 Client ID。遇到 identifier 已存在，请先由平台核对归属，不能通过重复创建绕过资源授权。

## JWT audience

合法资源请求在启用 JWT 插件的当前实现中获得 JWT access token。请求包含 `openid` 时，audience 还会包含 Auth 的 UserInfo 地址：

```json
{
  "iss": "https://auth.kai.com",
  "aud": [
    "https://exchange.kai.com",
    "https://auth.kai.com/api/auth/oauth2/userinfo"
  ],
  "scope": "openid profile email"
}
```

示例假设资源已注册、启用、允许这些 scope，并已授权给该客户端。`aud` 可为字符串或字符串数组。资源服务器检查自己的 identifier 是否属于 audience；不能要求 audience 只能等于 Auth issuer，也不能仅检查签名后忽略 audience。

UserInfo URL 是协议内置资源，不代表 Auth issuer 本身或其他 API 自动得到授权。不要使用内置资源作为绕开业务资源授权的方式。

## 有效期与校验

当前用户 access token 和 ID token 默认有效期均为 300 秒；资源策略可以进一步缩短 access token 生命周期。客户端使用实际响应的 `expires_in` / JWT `exp`，不假定固定寿命。

opaque token 无法通过本地 JWT 解码验证，需要调用 Introspection。鉴权成功的调用方还须是原发放客户端，或获准服务该令牌 audience 的资源服务器客户端；不相关客户端得到 `active: false`。没有资源 audience 的 opaque token 不能由任意其他客户端内省。

JWT 支持离线验签，但不会实时感知撤销状态。Auth 的在线 UserInfo 和 Introspection 会核对令牌所属的原始授权、授权版本及来源会话的认证修订号；撤销授权、缩减权限或修改账号安全设置后，旧令牌不能仅凭签名继续通过在线检查。恢复权限或重新授权不会复活旧 JWT。

对撤销时效敏感的资源服务器应使用获准的客户端认证调用 Introspection，并结合业务权限判断。仅做离线验证的 API 仍可能在 `exp` 到期前接受已撤销令牌。五个内部凭据字段的精确类型、刷新限制及升级时旧令牌的处理见[令牌校验与 claims](/docs/claims)。