概述 | Frame.io API Documentation

Frame.io V4 API 使用 Adobe Identity Management Service (IMS)，Adobe 的 OAuth 2.0 身份平台。共有两种身份验证类别：

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

让技术或服务帐户用户在无需用户交互的情况下执行操作。仅适用于通过 Adobe Admin Console 管理的 Frame.io V4 帐户。

用户身份验证

充当令牌所属用户。适用于通过 Adobe Admin Console 管理的所有 Frame.io V4 帐户，以及已切换到 Adobe 身份验证的 Frame 管理帐户。

SDK 身份验证指南

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

Python SDK

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

TypeScript SDK

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

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

用户身份验证

用户身份验证凭据在 Adobe Developer Console 中创建。 Adobe 支持三种凭据类型，请选择与您的应用程序架构匹配的类型：

OAuth Web 应用程序

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

OAuth 单页面应用程序

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

OAuth 原生应用程序

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

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

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

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

有关服务帐户设置的更多信息，请参阅使用 Frame.io 服务器到服务器支持实现您的设置自动化。

Adobe IMS 身份验证的工作原理

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

用户授权

首先，用户在生成令牌之前授权应用程序。详细信息请参阅此处。

令牌交换

接下来，获取访问令牌。上述步骤会在响应体中返回此步骤所需的代码。请参阅此处了解要访问的确切端点和要使用的参数。

上述步骤对于所有三种类型的应用程序凭据都是必需步骤。访问 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 特定的指南了解详细信息。

权限范围

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

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

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

旧版开发者令牌

对于已迁移到 V4 但尚未通过 Adobe Admin Console 进行管理的帐户，您可以继续使用在 Frame.io 开发者网站中管理的旧版开发者令牌。将令牌直接传递给 SDK：

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

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

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

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

有关从旧版令牌过渡到 Adobe IMS 身份验证的详细信息，请参阅迁移指南。