> This page is for 平台, version V4 实验版.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - 旧版: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# 身份验证

Frame.io V4 API 使用 [Adobe Identity Management Service (IMS)](https://developer.adobe.com/developer-console/docs/guides/authentication/)，Adobe 的 OAuth 2.0 身份平台。 共有两种身份验证类别：

#### 服务器到服务器的身份验证

让技术或服务帐户用户在无需用户交互的情况下执行操作。 仅适用于通过 [Adobe Admin Console](https://adminconsole.adobe.com) 管理的 Frame.io V4 帐户。

#### 用户身份验证

充当令牌所属用户。 适用于通过 Adobe Admin Console 管理的所有 Frame.io V4 帐户，以及[已切换到 Adobe 身份验证](https://help.frame.io/zh-CN/articles/11758018-connecting-to-adobe-authentication)的 Frame 管理帐户。

---

## SDK 身份验证指南

Frame.io SDK 为您处理完整的 OAuth 生命周期——包括授权 URL、令牌交换、自动刷新和撤销。选择您的语言以开始使用：

#### [Python SDK](./python-sdk)

`ServerToServerAuth`、`WebAppAuth` 和 `SPAAuth`，支持同步和异步模式。

#### [TypeScript SDK](./typescript-sdk)

`ServerToServerAuth`、`WebAppAuth`、`SPAAuth` 和 `NativeApp` 身份验证，适用于 Node.js 和浏览器环境。

> **Tip**
>
> 如果您正在构建后端服务或自动化功能，请从**服务器到服务器**开始。如果您的应用程序已有登录用户，请选择 **Web 应用程序**（如果您可以存储客户端密钥）或 **SPA**（如果您无法存储客户端密钥）。

---

## 用户身份验证

用户身份验证凭据在 [Adobe Developer Console](https://developer.adobe.com/console) 中创建。 Adobe 支持三种凭据类型，请选择与您的应用程序架构匹配的类型：

#### [OAuth Web 应用程序](https://developer.adobe.com/developer-console/docs/guides/authentication/UserAuthentication/implementation/#oauth-web-app-credential)

适用于可以安全存储客户端密钥的服务器端应用程序（Flask、Django、FastAPI、Express 等）。

#### [OAuth 单页面应用程序](https://developer.adobe.com/developer-console/docs/guides/authentication/UserAuthentication/implementation/#oauth-single-page-app-credential)

适用于基于浏览器的应用程序、CLI 或无法存储客户端密钥的桌面应用程序。 使用 PKCE。

#### [OAuth 原生应用程序](https://developer.adobe.com/developer-console/docs/guides/authentication/UserAuthentication/implementation/#oauth-native-app-credential)

适用于使用自定义 URI 方案重定向的原生移动或桌面应用程序。

> **Note**
>
> Frame.io Python SDK 不包含原生应用程序凭据类，因为 Python 没有用于注册自定义 URI 方案处理程序的标准方法。 请改用 **Web 应用程序**与本地回调服务器。 TypeScript SDK 支持所有三种凭据类型。

---

## 服务器到服务器的身份验证

服务器到服务器的身份验证让您的应用程序充当**服务帐户用户**，无需人工参与。 您的应用程序使用客户端凭据进行身份验证并直接接收访问令牌。 服务帐户操作在 Frame.io 中显示为服务帐户的名称。 服务帐户访问权限通过 [Adobe Admin Console](https://adminconsole.adobe.com/) 和 [Developer Console](https://developer.adobe.com/console) 进行管理。 服务帐户名称目前无法进行调整。 有关实施详细信息，请参阅上述 SDK 特定的指南。

> **Info**
>
> 有关服务帐户设置的更多信息，请参阅[使用 Frame.io 服务器到服务器支持实现您的设置自动化](https://helpx.adobe.com/enterprise/using/automate-using-frame-io.html)。

---

## Adobe IMS 身份验证的工作原理

Adobe Identity Management Service (IMS) 是 Adobe 基于 OAuth 2.0 的身份管理功能，支持身份验证。 生成访问令牌需要两个步骤：

#### 用户授权

首先，用户在生成令牌之前授权应用程序。 详细信息请参阅[此处](https://developer.adobe.com/developer-console/docs/guides/authentication/UserAuthentication/ims/#authorize-request)。

#### 令牌交换

接下来，获取访问令牌。 上述步骤会在响应体中返回此步骤所需的代码。 请参阅[此处](https://developer.adobe.com/developer-console/docs/guides/authentication/UserAuthentication/ims/#fetching-access-tokens)了解要访问的确切端点和要使用的参数。

> **Note**
>
> 上述步骤对于所有三种类型的应用程序凭据都是必需步骤。 访问 IMS 端点 `/authorize/v2` 和 `/token/v3` 获取令牌的方式有所不同。 在获得访问令牌后，您可以使用它与 Frame.io V4 API 交互。

对于**服务器到服务器**的身份验证，没有用户授权步骤，应用程序直接使用客户端凭据通过 `client_credentials` 授权凭据获取访问令牌。

### 使用访问令牌

获得访问令牌后，请将其包含在每个 API 请求的 `Authorization` 标头中：

```
Authorization: Bearer <ACCESS_TOKEN>
```

Frame.io SDK 会为您处理这一事项，只需在创建客户端时传递令牌（或提供令牌的可调用对象）。

### 令牌 TTL

访问令牌**短期有效**，通常在 1 小时后过期。 对于用户身份验证流程（Web 应用程序、SPA、原生应用程序），Adobe IMS 还会返回**刷新令牌**，可用于获取新的访问令牌，而无需用户再次登录。 刷新令牌的有效期较长，但最终也会过期。

对于服务器到服务器的身份验证，没有刷新令牌。 客户端凭据本身永不过期（除非手动轮换），因此应用程序始终可以请求新的访问令牌。

Frame.io SDK 会自动处理令牌刷新，请参阅 [SDK 特定的指南](#sdk-authentication-guides)了解详细信息。

### 权限范围

在 [Adobe Developer Console](https://developer.adobe.com/console) 中创建凭据时，您将需要配置 OAuth 权限范围来确定应用程序可以访问的内容。 Frame.io SDK 使用以下默认权限范围：

| 流程                              | 默认权限范围                                                      |
| ------------------------------- | ----------------------------------------------------------- |
| **服务器到服务器**                     | `openid AdobeID frame.s2s.all`                              |
| **用户身份验证**（Web 应用程序、SPA、原生应用程序） | `openid email profile offline_access additional_info.roles` |

> **Note**
>
> 用户身份验证流需要 `offline_access` 权限范围才能接收刷新令牌。 如果没有这个权限范围，您将只会获得访问令牌，用户需要在令牌过期时重新进行身份验证。

---

## 旧版开发者令牌

对于已迁移到 V4 但**尚未通过 [Adobe Admin Console](https://adminconsole.adobe.com/) 进行管理**的帐户，您可以继续使用在 [Frame.io 开发者网站](https://developer.frame.io/app/tokens)中管理的旧版开发者令牌。 将令牌直接传递给 SDK：

```python
from frameio import Frameio

client = Frameio(
    token="YOUR_LEGACY_DEVELOPER_TOKEN",
    headers={"x-frameio-legacy-token-auth": "true"},
)
```

> **Warning**
>
> 在 V4 API 中使用旧版开发者令牌时，您必须在所有 API 请求中添加值为 `true` 的 `x-frameio-legacy-token-auth` 标头。 如果您使用 SDK，请通过客户端的请求选项进行设置。

旧版开发者令牌不会过期，但它们是一种过渡机制。 对于新的集成和生产工作负载，我们推荐使用下面的其中一个 OAuth 2.0 流。 有关详细信息，请参阅[迁移指南](/platform/docs/resources/migration#authentication)。

> **Note**
>
> 如果您是要从 Frame.io 旧版迁移到 V4 的企业客户，请联系您的客户成功经理 (CSM) 获取有关设置旧版开发者令牌和 V4 的帮助

> **Tip**
>
> 有关从旧版令牌过渡到 Adobe IMS 身份验证的详细信息，请参阅[迁移指南](/platform/docs/resources/migration#authentication)。