> 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 Experimental: 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 の実装：セットアップ](https://developer.frame.io/docs/device-integrations/implementing-c2c-setting-up)ガイドをまだ読んでいない場合は、目を通してから先へ進んでください。

当社のチームから提供された `client_secret` と、[認証および承認ガイド](https://developer.frame.io/docs/device-integrations/implementing-c2c-authentication-and-authorization-hardware)で使用したものと同じ `client_id` が必要です。このガイドを完了するには、`access_token` と `refresh_token` も必要です。

## 承認トークン

[直前のガイド](https://developer.frame.io/docs/device-integrations/implementing-c2c-authentication-and-authorization-hardware)では、ユーザーにプロジェクト上のデバイスを認証および承認してもらうことで新しい承認トークンを生成する方法を学習しました。 **

アクセストークンは、有効期限が切れる前に最大 8 **時間持続します。デバイスのユーザーが 8 時間ごとにデバイスをペアリングする必要性は排除したいことから、最後のガイドでは `offline` **スコープをリクエストし、Frame.io での承認時に更新トークンも取得しました。更新トークンは、現在のトークンの有効期限が切れた場合に新しいアクセストークンの生成に使用できます。

更新トークンの有効期限は 14 **日です。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://api.frame.io/v2/auth/token \
    --header 'x-client-version: 2.0.0' \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'grant_type=refresh_token' \
    --form 'refresh_token=[refresh_token]' \
    | python -m json.tool
```

<Info title="API エンドポイント仕様">
`/v2/auth/token` のドキュメントは[こちら](https://developer.frame.io/api/reference/operation/authDeviceRefreshToken/)に用意されています
</Info>

<Info title="これらの値になじみがありませんか？">
これらの値はすべて、[前のガイド](https://developer.frame.io/docs/device-integrations/implementing-c2c-authentication-and-authorization-hardware)で生成されたものです。まだの場合は、確認してからこちらに戻ってきてください。
</Info>

更新トークンだけではなく、これらすべての値を使用することで、漏洩した更新トークンでは新しい承認をオンラインで生成できないようになっています。誰かが統合になりすましてトークンを生成しようとしても、`refresh_token` と `client_secret` **の両方が必要となります。

次のようなレスポンスが返されます。

```json
{
    "access_token": "[access_token]",
    "expires_in": 28800,
    "refresh_token": "[refresh_token]",
    "token_type": "bearer"
}
```

これらは新しい承認トークンです。トークンを更新すると、古いトークンは機能しなくなるので、これらをいつでも参照できるようにしておいてください。 **

古い更新トークンを使用して今すぐ更新しようとすると、次のエラーが返されます。

```json
{
    "error": "invalid_request"
}
```

トークンが更新済みなので、既存の更新トークンの使用は無効です。

<Error title="更新中の 401 レスポンス">
トークンの更新中に `401 Not Authorized` レスポンスが返された場合、トークンはすでに無効になり、認可プロセスを最初からやり直す必要があります。
</Error>

## 更新レスポンスの欠落

`refresh_token` 値は 1 回だけ使用できます。Frame.io **を呼び出してトークンを更新したが、ネットワークエラーまたは予期しないパワーサイクルが原因でレスポンスを受け取りそこねた場合は、認証／承認フロー全体をやり直す必要があります。

これは不運な可能性ですが、面倒でも安全性を優先してください。

## トークンの取り消し

Frame.io から「ログアウト」したいという状況が考えられます。例えば、撮影完了後のユーザーが接続状態を望まない場合です。アプリが悪い状態に陥り、クリーンな状態にリセットする必要がある場合も、承認の取り消しは良い慣行です。現在の承認を破棄する予定がある場合は、その承認の取り消しをアプリが試行する必要があります。

承認を取り消すには、次の呼び出しを実行します。

<Info title="再認可">
この呼び出しの実行後、[前のガイド](https://developer.frame.io/docs/device-integrations/implementing-c2c-authentication-and-authorization-hardware)で詳しく説明している認証および認可プロセスをやり直す必要があります。
</Info>

```shell
curl -X POST https://api.frame.io/v2/auth/revoke \
    --include \
    --header 'x-client-version: 2.0.0' \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'token=[refresh_token]
```

<Info title="API エンドポイント仕様">
`/v2/auth/revoke` のドキュメントは[こちら](https://developer.frame.io/api/reference/operation/authDeviceRevokeToken/)に用意されています
</Info>

レスポンスにペイロードは含まれません。ここでは、コマンドで `--include` を使用して、返されたヘッダーを出力しています。呼び出しが成功した場合、ヘッダーはステータスコード `200` で始まっているはずです。

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

トークンが取り消されたので、`access_token` を必要とするすべての [Frame.io](http://frame.io/) 呼び出しには `Not Authorized` が返されます。ユーザーが Frame.io 接続を再度使用する場合は、デバイスをプロジェクトと再度ペアリングする必要があります。

## トークンの保存

パワーサイクルをまたいで機能を維持するためには、承認ヘッダーを永続的に保存しておく必要があります。これは、ファイル、データベースまたは独自のクラウドで実現できます。承認トークンを保存するためのガイドラインは次のとおりです。

**ユーザーによるトークンの表示やアクセスを許可しないでください**。ユーザーによる自身のトークンの表示または取得は許可されるべきものではありません。これらは、アプリのみで管理する必要があります。

**保管するトークンは暗号化してください。**`client_secret` と同様、アクセストークンと更新トークンは、可能な場合は保存時に暗号化して、鍵の盗難を防ぐ必要があります。*承認鍵をプレーンテキストで保存しないでください。*

**承認トークンを client_secret と同じファイルに保存しないでください。**Python アプリの例では `client_secret` と `client_id` を承認トークンと同じファイルに保存しています。これは、デモでは問題ありませんが、本番環境のコードでは適切な慣行ではありません。`client_secret` と `client_id` **はデバイスの静的な値であり、これらが失われるとデバイスが機能を停止します。

承認トークンは静的ではなく、デバイスの有効期間中に何度も書き直しが必要となります。新しいトークンを使用してファイルを更新している最中にデバイスが電源を喪失すると、そのファイルが破損して `client_secret` **が失われ、以降、そのデバイスを Frame.io で再認証できなくなる可能性があります。トークンを分けておけば、最悪の場合でも、ユーザーはデバイスをペアリングすれば済みます。

トークンの保管に最適な場所は、SQLite のような実績あるデータベースですが、少なくとも承認データを他の値と分けておく必要があります。

## 次のステップ

まだの場合は、当社チームにお問い合わせください。そのうえで、次のガイドに進んでください。ご連絡をお待ちしております。