> This page is for 平台, version 旧版.
> 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 的 *C2C 应用程序* 授权信息。





## 我需要准备什么？

如果您还未阅读[实施 C2C：设置](/camera-to-cloud/implementing-c2c-setting-up)指南，请先快速浏览一下再继续操作！您需要用到我们团队提供给您的 `client_id`，以及您在[身份验证和授权指南](/platform/v2/implementing-c2c-authentication-and-authorization-c2c-application)中使用的同一个 `device_id`。完成本指南还需要 `access_token` 和 `refresh_token`。

## 授权令牌

在[上一篇指南](/platform/v2/implementing-c2c-authentication-and-authorization-c2c-application)中，我们学习了如何通过让用户在项目上进行身份验证和授权设备来 *生成* 新的授权令牌。*访问令牌在约 1 小时后过期*。我们不希望设备用户每 8 小时就要登录一次，因此在上一篇指南中我们请求了 `offline` 权限范围，并且在通过 Frame.io 授权时也获得了 *刷新令牌*。刷新令牌可用于在当前访问令牌过期时生成一个新的访问令牌。

*刷新令牌的有效期为 30 天*。通过限制 access_token 的有效时间，我们可以限制在令牌泄露时可能发生的潜在恶意行为。如果在使用 *刷新令牌* 之前没有刷新授权，用户将不得不重新进行身份验证。





## 刷新您的访问令牌





如果您向我们的 API 发起需要访问令牌的调用，并收到以下响应：





```json
{
    "code": 401,
    "errors": [
        {
            "code": 401,
            "detail": "You are not allowed to access that resource",
            "status": 401,
            "title": "Not Authorized"
        }
    ],
    "message": "Not Authorized"
}
```





…那您的访问令牌已经过期了！





为了刷新您的令牌，我们将进行以下调用：





```shell
curl -X POST https://applications.frame.io/oauth2/token \
    --form 'client_id=[client_id]' \
    --form 'scope=offline device.connect asset.create' \
    --form 'grant_type=refresh_token' \
    --form 'refresh_token=[refresh_token]' \
    | python -m json.tool
```




<Info title="不确定这些值是什么吗？">
  所有这些值都是在[上一篇指南](/platform/v2/implementing-c2c-authentication-and-authorization-c2c-application)中生成的。如果您还没有查看，请先查阅上一篇指南，然后再回到这里！
</Info>
 通过使用所有这些值（而不仅仅是刷新令牌），我们可以防止人们仅凭泄露的刷新令牌在线生成新的授权。如果有人想要冒充您的集成来生成令牌，他们将需要同时获取 `refresh_token` *和* `client_id`。

您应该会收到类似如下的响应：





```json
{
    "access_token": "[access_token]",
    "expires_in": 3599,
    "refresh_token": "[refresh_token]",
    "scope": "offline device.connect asset.create",
    "token_type": "bearer"
}
```





这些就是您的新授权令牌。*刷新令牌后，旧令牌将不再有效*，因此请务必妥善保管这些新令牌！





如果我们现在尝试使用旧的刷新令牌进行刷新，将会收到一个错误：





```json
{
    "error": "token_inactive",
    "error_description": "Token is inactive because it is malformed, expired or otherwise invalid. Token validation failed."
}
```





我们的令牌已经刷新，因此使用原有的刷新令牌是无效的。




<Error title="在刷新过程中收到 401 错误">
  如果您在刷新令牌时收到 `401 Not Authorized` 响应，则表示您的令牌已不再有效，您需要重新启动整个授权流程。
</Error>


## 缺少刷新响应





*刷新令牌只能使用一次*。如果您向 Frame.io 发起刷新令牌的调用，但由于网络错误或意外断电而错过了响应，那么 *您将需要重新启动整个身份验证/授权流程*。





这种情况固然令人遗憾，但有备无患总是好的！





## 撤销令牌





在某些情况下，我们可能希望“退出”Frame.io。例如，用户可能在完成拍摄后决定不再希望保持连接。如果您的应用程序进入异常状态并需要重置为干净状态，撤销授权也是一个很好的做法。每当您打算放弃当前授权时，您的应用程序都应尝试将其撤销。





为了撤销我们的授权，我们将进行以下调用：




<Info title="重新授权">
  进行此调用后，您需要重新启动[上一篇指南](/platform/v2/implementing-c2c-authentication-and-authorization-c2c-application)中详述的身份验证和授权流程。
</Info>


```shell
curl -X POST https://applications.frame.io/oauth2/revoke \
    --include \
    --form 'client_id=[client_id]' \
    --form 'token=[refresh_token]'
```

响应将不包含负载。我们在命令中使用了 `--include` 来打印返回的标头，如果调用成功，标头应该以状态代码 `200` 开头：

```text
HTTP/2 200
...
```

现在我们的令牌已被撤销，所有需要 `access_token` 的对 [Frame.io](http://frame.io/) 的调用都将返回 `Not Authorized`；如果用户希望再次使用 Frame.io 连接，他们需要重新登录 Frame.io 并连接到项目。

## 存储令牌





为了在多次电源循环后仍能保持功能，您需要静态存储您的 Authorization 标头。这可以通过文件、数据库或您自己的云来实现。以下是存储授权令牌的一些指南：

**不要让用户看到或访问这些令牌**。绝不允许您的用户查看或检索他们的令牌。令牌应由您的应用程序单独管理。**静态加密您的令牌。**就像 `client_id` 一样，访问和刷新令牌在可能的情况下应该静态加密，以防止密钥被盗。*授权密钥不应以明文形式存储。* **不要将您的授权令牌与您的 client_id 存储在同一个文件中。**示例 Python 应用程序将 `client_id` 和 `device_id` 与其授权令牌存储在同一个文件中。这对于演示来说没问题，但对于生产代码来说不是一个好做法。`client_id` 和 `device_id` 是设备的静态值，*如果丢失，设备将停止运行。* 授权令牌不是静态的，在设备的生命周期内需要被多次重写。如果在使用新令牌更新文件时设备断电，该文件可能会损坏，并且 `client_id` 可能会丢失，导致设备 *再也无法* 在 Frame.io 上重新进行身份验证。通过将令牌分开存储，最坏的情况下，用户只需要再次登录 Frame.io 即可。

存储令牌的最佳位置是像 SQLite 这样经过验证的数据库，但至少，授权数据应该与我们的其他值分开存储。





## 下一步





如果您还没有联系我们的团队，我们鼓励您这样做，然后继续阅读下一份指南。我们期待收到您的回复！