# @auth0/auth0-api-js 中文文档

规范地址：https://npmcn.com/package/%40auth0/auth0-api-js/

版本：1\.7\.0
npm 元数据更新时间：2026-10-21T13:34:40.119Z
中文译文更新时间：2026-11-07T05:52:37.476Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40auth0/auth0-api-js
原文对照：https://npmcn.com/package/%40auth0/auth0-api-js/?lang=original
项目主页：https://github.com/auth0/auth0-auth-js#readme
源码仓库：https://github.com/auth0/auth0-auth-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：611 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-03-28T13:09:07.454Z
- 最新版本发布：2026-10-21T13:34:39.635Z
- 近 30 天下载量：263609（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 6 个）

## 中文简介

Auth0 认证 SDK 对 JavaScript 运行时间的 API

## 安装

```sh
npm install @auth0/auth0-api-js
```

也可以使用：`pnpm add @auth0/auth0-api-js`、`yarn add @auth0/auth0-api-js`、`bun add @auth0/auth0-api-js`

## README

这个 `@auth0/auth0-api-js` 库允许在 JavaScript 运行时确保 API 运行 .

在您的 API 中使用 SDK 可能不是微不足道的, 因为它不是您框架的插件和游戏库 。 取而代之,它被设计为构建框架特有SDK的构件.

![Release](https://img.shields.io/npm/v/@auth0/auth0-api-js) ![Downloads](https://img.shields.io/npm/dw/@auth0/auth0-api-js) [![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)

📚 [文档](https://npmcn.com/package/%40auth0/auth0-api-js/#readme-documentation) - 🚀 [开始](https://npmcn.com/package/%40auth0/auth0-api-js/#readme-getting-started) - 💬 [反馈](https://npmcn.com/package/%40auth0/auth0-api-js/#readme-feedback)

## 文档

-   [Docs 站点](https://auth0.com/docs) - 探索我们的文件网站 了解更多关于Auth0.

## 开始

### 1\. 安装SDK

```shell
npm i @auth0/auth0-api-js
```

这个库需要Node.js 20 LTS和较新的LTS版本.

### 2\. 创建 Auth0 SDK 客户端

创建实例 `ApiClient`。这个实例将被导入并用于我们需要获取方法的任何地方.

```ts
import { ApiClient } from '@auth0/auth0-api-js';

const apiClient = new ApiClient({
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
});
```

这个 `AUTH0_DOMAIN` 可从 [Auth0 剪贴板](https://manage.auth0.com/) 一旦你创建了一个应用程序. 这个 `AUTH0_AUDIENCE` 是 API 的标识符。 您可以在 Auth0 仪表板的 API 部分中找到这个 .

### 3\. 验证访问托肯

SDK的车 `verifyAccessToken` 方法可用于验证访问符.

```ts
const apiClient = new ApiClient({
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
});

const accessToken = '...';
const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
  accessToken,
});
```

SDK自动验证索赔 `iss`, (中文(简体) ), `aud`, (中文(简体) ), `exp`,以及 `nbf`。您也可以通过配置来通过所需的额外索偿 `requiredClaims`数字 :

```ts
const apiClient = new ApiClient({
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
});

const accessToken = '...';
const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
  accessToken,
  requiredClaims: ['my_custom_claim'],
});
```

当下游的API收到通过OBO签发的令牌时,经核实的索赔可能包括: `act` 索赔。 在这个情景中,下游API验证了符号,证实目前的演员是预期的 `MCP` 服务器,并记录整个授权链用于审计记录:

```ts
import { getCurrentActor, getDelegationChain } from '@auth0/auth0-api-js';

const claims = await apiClient.verifyAccessToken({ accessToken });
const currentActor = getCurrentActor(claims);
const delegationChain = getDelegationChain(claims);

// Authorize only the current actor.
if (currentActor && currentActor !== 'mcp_server_client_id') {
  throw new Error('Unexpected actor');
}

// Use the full chain for logging or audit only.
auditLogger.info('delegated_request', {
  user: claims.sub,
  currentActor,
  delegationChain,
});
```

只有最外层 `act.sub` 应用于作出授权决定。 使用 `delegationChain` 用于伐木、审计或归属.

### 4\. 验证 DPoP 访问托肯斯

这个 `verifyAccessToken` 方法还支持验证 DPop 绑定访问符.

使用时 `DPoP`您必须提供 `scheme`, (中文(简体) ), `dpopProof`, (中文(简体) ), `httpMethod`,以及 `httpUrl` 从收到的 HTTP 请求中可以让 SDK 验证证据,并确保令牌与该请求相接.

```ts
const apiClient = new ApiClient({
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
  dpop: {
    mode: 'required', // optional, defaults to 'allowed'
    iatOffset: 400, // optional, defaults to 300 seconds
    iatLeeway: 30, // optional, defaults to 30 seconds
  },
});

const accessToken = '...';
const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
  accessToken,
  requiredClaims: ['my_custom_claim'],
  // Options required for DPoP bound token verification
  scheme: '<AUTHENTICATION_SCHEME>',
  dpopProof: '<DPOP_PROOF_JWT>',
  httpMethod: '<HTTP_METHOD>',
  httpUrl: '<HTTP_REQUEST_URL>'
});
```

见 [DPop 认证](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-api-js/EXAMPLES.md#dpop-authentication) 内 [缩略语.md](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-api-js/EXAMPLES.md) 更多的例子和细节.

### 5\. 保护资源元数据(RFC 9728)

SDK 支持 OAuth 2.0 保护资源元数据,定义如下: [RFC 9728 (英语)](https://datatracker.ietf.org/doc/html/rfc9728)数字 :

```ts
import {
  ProtectedResourceMetadataBuilder,
  BearerMethod,
  SigningAlgorithm,
} from '@auth0/auth0-api-js';

const resourceServerUrl = 'https://api.example.com';
const authServers = ['https://your-tenant.us.auth0.com'];

const metadata = new ProtectedResourceMetadataBuilder(resourceServerUrl, authServers)
  .withBearerMethodsSupported([BearerMethod.HEADER])
  .withResourceSigningAlgValuesSupported(
    SigningAlgorithm.RS256,
    SigningAlgorithm.ES256,
  )
  .withScopesSupported(['read', 'write', 'admin'])
  .build();

// Serve metadata from the standard RFC 9728 endpoint
app.get('/.well-known/oauth-protected-resource', (req, res) => {
  res.json(metadata.toJSON());
});
```

### 6\. 托肯交易所

SDK支持 RFC 8693 OAuth 2. Token Exchange,允许您在保存用户身份的同时,为不同的API受众交换令牌.

#### 何时使用哪个流程

-   **自定义托肯交换**: 当控制主题符号格式时使用。 常见情况:
    
    -   交换 Auth0 的 MCP 服务器令牌
    -   从遗留的认证系统迁移
    -   与伙伴系统采用自定义符号格式
    -   由您服务单位签发的换证
-   **与 Token Vault 访问托肯交换** (通过) `getAccessTokenForConnection`: 交换外部提供者的访问符时使用:
    
    -   使用用户的 Google 令牌访问 Google API
    -   使用用户的 Facebook 令牌调用 Facebook Graph API
    -   Auth0 管理 Token 断层中外部提供者刷新符的任意情景

#### 自定义托肯交换示例

```ts
import { ApiClient } from '@auth0/auth0-api-js';

const apiClient = new ApiClient({
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
  clientId: '<AUTH0_CLIENT_ID>',
  clientSecret: '<AUTH0_CLIENT_SECRET>',
});

// Exchange a custom token (e.g., from an MCP server or legacy system)
const result = await apiClient.getTokenByExchangeProfile(
  userToken, // The token to exchange
  {
    subjectTokenType: 'urn:example:custom-token', // Your custom token type URN
    audience: 'https://api.backend.com',
  }
);

// Handle token expiry - check expiresAt and re-exchange when needed
// Note: expiresAt is in seconds, Date.now() is in milliseconds
const tokenIsValid = Math.floor(Date.now() / 1000) < result.expiresAt;
if (!tokenIsValid) {
  // Re-exchange with a fresh subject token (e.g., from your auth provider)
  const newSubjectToken = await getNewTokenFromYourProvider();
  const refreshed = await apiClient.getTokenByExchangeProfile(newSubjectToken, {
    subjectTokenType: 'urn:example:custom-token',
    audience: 'https://api.backend.com',
  });
}
```

> **安全说明**编号: `extra` 参数(如果在应用程序中暴露)绝不应包含个人识别信息或敏感数据。 额外的参数可能由Auth0记录或包含在审计线索中. 只用于不识别用户的非敏感技术参数.

学习更多: [自定义托肯交换](https://auth0.com/docs/authenticate/custom-token-exchange) | [托肯断层](https://auth0.com/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault)

#### 在 Token 半个交换示例上

使用 `getTokenOnBehalfOf()` 当您的 API 接收到 `Auth0` 自身和需求访问符 换成另一个 `Auth0` 在保护下游 API 时, 访问符 同样的用户身份。 这对 `MCP` 服务器和其他中间API 需要代表用户调用下游API.

以下示例验证您 API 的进取访问令牌, 将它交换为下游 API 的令牌, 然后用交换令牌调用下游 API .

```ts
function getBearerToken(authorizationHeader: string | null): string {
  if (!authorizationHeader?.toLowerCase().startsWith('bearer ')) {
    throw new Error('Missing Bearer access token');
  }

  return authorizationHeader.slice('Bearer '.length).trim();
}

export async function handleCalendarRequest(request: Request) {
  const incomingAccessToken = getBearerToken(request.headers.get('authorization'));

  await apiClient.verifyAccessToken({ accessToken: incomingAccessToken });

  const obo = await apiClient.getTokenOnBehalfOf(incomingAccessToken, {
    audience: 'https://calendar-api.example.com',
    scope: 'calendar:read calendar:write',
  });

  const downstreamResponse = await fetch('https://calendar-api.example.com/events', {
    headers: {
      authorization: `Bearer ${obo.accessToken}`,
    },
  });

  if (!downstreamResponse.ok) {
    throw new Error(`Downstream request failed with ${downstreamResponse.status}`);
  }

  return downstreamResponse.json();
}
```

`getTokenOnBehalfOf()` 将收到的访问符号转发为 [RFC 8693 (法语)](https://datatracker.ietf.org/doc/html/rfc8693#section-2.1) `subject_token` 无效 交换期间,DPoP自有的处理. 当您提供一个代号商店(见下文), SDK 在交换前还要核实主题符号. 这个 `OBO` 结果仅包括面向访问的字段。 它不会暴露 `id_token` 或者说 `refresh_token`。 。 。 .

#### 缓存 OBO 标志

传递带有 a 的上下文对象 `store` 作为避免在每次请求中调用Auth0的第三个论据. SDK在交换前检查商店,并将结果写回成功. 无内置 ; 提供执行 `TokenStore` 接口.

```ts
const obo = await apiClient.getTokenOnBehalfOf(
  incomingAccessToken,
  { audience: 'https://calendar-api.example.com', scope: 'calendar:read calendar:write' },
  { store }
);
```

在你依赖它之前要知道的一些行为:

-   **核实取决于商店.** 如果而且只有在商店是 提供,因为缓存需要它的主张来构建缓存密钥. 没有商店,代号是 已转发。 和商店和没有 `verified` sDK在上下文中核查 作为无请求语境的熊鼠指使符,不能满足 `dpop: { mode: 'required' }`, (中文(简体) ), 无法接受 DPOP 绑定符,并给出 `domains` 解析器没有 URL 和信头 。 在那个 并传递结果为 `{ store, verified: { accessToken, claims } }`。 。 。 .
-   **`verified.claims` 必须是对象 `verifyAccessToken` 回到同一个地方 `ApiClient`。 。 。 .** 这个 SDK对照私人注册处检查物体身份 所以这些是手工制造的 克隆的, 通过JSON进行回转 `ApiClient` 实例或发送到 工序或工人边界以 `InvalidConfigurationError`编辑 `accessToken` 债权不得过期: `exp` 位于或位于 拒绝当前时间的几秒钟。 这两张支票 `VerifyAccessTokenError` (单位:千美元)`invalid_token`,与通常的挑战头),因为它们涉及呼叫者的标志和 而不是整合。 限制之所以存在,是因为缓存密钥是 根据这些索赔。 如果接受未经核实的索偿要求,可以由打电话者阅读或覆盖 另一本金的缓存代币。 当入侵和交换 运行在不同的 进程、调用 `verifyAccessToken` 再次在交换方面。 本地验证是便宜的 因为JWKS是缓存的.
-   **范围匹配.** 这个 `scopeMatching` 选项 `ApiClient` 实值 `'strict'` (违约)或 `'non_strict'`两者都比较了准予交换的范围. `'strict'` 只重用一个符号 当它被授予的范围等于要求的一组. `'non_strict'` 也可以重新使用其授权的标志 范围涵盖请求,并要求 `IndexedTokenStore`;否则将发出一个 `InvalidConfigurationError`。条目存放在它们原来的范围 **获准**,则a `'strict'` 检索使用新请求的确切范围集. 申请在赠款时按 等于请求。 包括没有答复的答复 `scope`,这意味着补助金与 请求。 Auth0 缩小或拓宽的赠款存放在与它不同的套件中 请求中, 因此重复相同的请求会错失, 每次重交换 . `'non_strict'` 服务 任何缓存信使的请求,其授权范围包括其中,包括更广泛的赠款.
-   **有限的赠款在此不被拒绝.** 如果 Auth0 授予的范围比请求的要少, 则符号 被缓存在它批准并返回的范围之下 `scope` 确定授权内容 服务器已发送 。 这一一揽子方案并不决定这是否可接受。 服务于 请求确实如此,因为它的背景是将数额有限的赠款转化为正确的响应。 检查 `grantedScopes` 如果您需要每个请求的范围,则使用结果。 它总是在,在新鲜的 交换和缓存击出, 它被规范化,被复制和排序。 与 `scope`,这个 当服务器省略时,报告请求的集 `scope`,而范围更广的缓存符号 进行非限制性的打击,以达到更窄的要求。 不测试 `scope` 对于真理:一个空的 字符串表示什么也没有被授予,并且不同于没有的字段,这意味着 根据请求授予了范围(RFC 6749 第5.1节),因此 `if (result.scope)` 读取为空 赠款作为全额赠款.
-   **密钥请求类型错误的令牌不会被缓存 .** 若为 `iss`, (中文(简体) ), `client_id`, (中文(简体) ), `azp`, (中文(简体) ), `sub`, (中文(简体) ), `org_id`, (中文(简体) ), `sid` 或者说 `jti` 以非字符串值显示,调用收益为普通无标记 交换。 一个符合要求的标志永远不会触发这个.
-   **库存合同.** 返回的条目必须将其字段暴露为自己的属性,因为 字段读取 `Object.hasOwn`。普通物体和 `JSON.parse` 输出工作; 类 以原型获取器读取为空并失真。 记录或索引成员 超过1 000个瞄准镜被拒,因为其结构不当,非限制性匹配最多为20名候选人 每个查询条目。 索引是一个提示:指向不匹配自己的密钥的成员 记录的瞄准镜被跳过。 此软件包从不删除或删除条目或索引成员, 所以 驱逐属于你的执行.
-   **退取之窗.** 缓存密钥的会话组件会比任何单个访问符都久远, 所以 a 届会早些时候铸造的委托代币重新用于同一届会的后期代币。 A 类 在授权服务器上取消的会话不会使已缓存的授权令牌无效 在那个信物过期之前 这对缓存授权的代币是固有的.
-   **商店故障从不失败.** 读出一个扔出,一个不正确的条目和一个条目关闭 中,所有缓存都丢失,并且一个丢出仍然返回新符号的写入.
-   **保护活物.** 缓存密钥不透明, 在清晰处没有请求值, 但是 此软件包不应用加密 。 由共享或持续存储支撑的商店负责 保护它所持有的象征物.

见 [用托肯斯托雷来吊死OBO标志](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-api-js/EXAMPLES.md#caching-obo-tokens-with-a-tokenstore) 内 [缩略语.md](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-api-js/EXAMPLES.md) 包括有缓存的DPoP、索引商店、 `CachedToken` 形状 和责任界限.

### 7\. 客户证书(机器对机器)

SDK支持OAuth 2.0客户端认证授权,该授权允许保密客户端(服务器侧应用程序有客户端秘密或私人密钥JWT)在没有用户参与的情况下获得访问令牌. 这是机对机(M2M)通信的标准模式,如背景工作或微服务呼叫下游API.

要使用此流量, 您必须配置 `ApiClient` 具有客户资格:

```ts
import { ApiClient } from '@auth0/auth0-api-js';

const apiClient = new ApiClient({
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
  clientId: '<AUTH0_CLIENT_ID>',
  clientSecret: '<AUTH0_CLIENT_SECRET>',
});

// Request a token using the audience configured at construction time.
const tokenSet = await apiClient.getClientCredentialsToken({});
```

您也可以覆盖观众, 或通过一个范围给给定的电话:

```ts
// Override audience and request specific scopes.
const tokenSet = await apiClient.getClientCredentialsToken({
  audience: 'https://api.backend.com',
  scope: 'read:data write:data',
});

// Use the access token to call a downstream API.
const response = await fetch('https://api.backend.com/data', {
  headers: {
    authorization: `Bearer ${tokenSet.accessToken}`,
  },
});
```

`scope` 被转发到符号端点,将白空间正常化为单个空间。 过 `null` 或放它出去 以发出没有范围。 空或非字符串值抛出 `InvalidScopeError` 在提出任何请求之前,因为Auth0会视之为省略并发放全额赠款。 Auth0 不将签发的令牌缩入请求 `scope`,所以读出授予 `scope` 以观察一切迹象。 这需要 `@auth0/auth0-auth-js` 1.1.8.0 或较后.

方法返回 a `TokenSet` 具有下列属性的对象:

-   `accessToken`: Auth0发布的访问令牌.
-   `expiresAt`:自Unix时代起,标志性过期时间为秒.
-   `scope`: 授权服务器所授予的范围, 由于一个空间限制字符串正按给定的返回 。 缺席 `scope` 是指根据请求授予的范围(RFC 6749 第5.1节)。 空字符串意味着没有被允许。 将两者分开,测试 `undefined` 而不是为虚假.
-   `tokenType`: 符号类型, 由基本的 OAuth 客户端规范为小写, 所以一个无记名符号会以 `bearer`。 。 。 .

要检查一个符号是否在使用前过期, 请比较 `expiresAt` 改为当前时间 :

```ts
// expiresAt is in epoch seconds; Date.now() is in milliseconds.
const isExpired = Math.floor(Date.now() / 1000) >= tokenSet.expiresAt;
```

> **所需资源**编号: `ApiClient` 必须用其中之一来构建 `clientSecret` 或者说 `clientAssertionSigningKey`调用 `getClientCredentialsToken()` 不配置客户端认证 `MissingClientAuthError`。 。 。 .

见 [客户证书](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-api-js/EXAMPLES.md#client-credentials-machine-to-machine) 实例 [缩略语.md](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-api-js/EXAMPLES.md) 更多细节.

## 反馈

### 捐款

我们赞赏反馈和对这次再投资的贡献! 在开始前,请阅读以下内容:

-   [Auth0的一般贡献准则](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
-   [Auth0 行为守则准则](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
-   [这个Repo的贡献指南](https://github.com/auth0/auth0-auth-js/blob/main/CONTRIBUTING.md)

### 提出问题

请提供反馈或报告错误 [提出我们的问题追踪器](https://github.com/auth0/auth0-auth-js/issues)。 。 。 .

## 脆弱性报告

请不要在公共 GitHub 问题跟踪器上报告安全漏洞 。 这个 [负责任的披露程序](https://auth0.com/responsible-disclosure-policy) 详细说明披露安全问题的程序.

## 什么是奥特?

![Auth0 Logo](https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png)

Auth0是一个易于执行,可适应的认证和授权平台. 学习更多退房 [为什么是Auth0?](https://auth0.com/why-auth0)

这个项目根据麻省理工学院的许可证获得许可。 见 [自由主义](https://github.com/auth0/auth0-auth-js/blob/main/packages/auth0-api-js/LICENSE) 需要更多信息的文件.

## 常见问题

### @auth0/auth0-api-js 是什么？

Auth0 认证 SDK 对 JavaScript 运行时间的 API

### 如何安装 @auth0/auth0-api-js？

在项目目录运行 npm install @auth0/auth0-api-js，或使用 pnpm add / yarn add / bun add。

### @auth0/auth0-api-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @auth0/auth0-api-js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @auth0/auth0-api-js 可以商用吗？

@auth0/auth0-api-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @auth0/auth0-api-js 的下载量有多少？

根据 npm 官方下载统计，@auth0/auth0-api-js 在 2026/10/07 – 2026/11/05 这 30 天内被下载 263,609 次，日均约 8,787 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @auth0/auth0-api-js 还在维护吗？

最新版本 1\.7\.0 发布于 2026/10/21（17 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。