# General Translation Platform: API キー
URL: https://generaltranslation.com/ja/docs/platform/dashboard/reference/api-keys.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: アプリ、ローカル開発、自動化向けの プロジェクト および Organization の API キーを作成、管理します。API キーのリファレンス。

API キーは、アプリ、CLI、自動化を General Translation で認証するために使用します。ワークフローに適した範囲で、最も限定的なキーのスコープを使用してください。

## キーのスコープ [#key-scopes]

General Translation は 2 つの API キー のスコープをサポートしています。

* Organization レベルの自動化には **Organization キー** を使用します。Organization 内の複数の プロジェクト をまたいで動作する必要がある、組織レベルの自動化や ワークフロー に使用してください。
* 単一の プロジェクト には **プロジェクト キー** を使用します。server 環境、ローカル開発、プロジェクト スコープのツールに使用してください。デプロイされた ブラウザ やモバイルの app bundle には絶対に含めないでください。

Dashboard では、どちらのスコープも **All** または **Custom** の 権限 をサポートしています。**All** は、そのスコープ内で委任できるすべての 権限 を付与します。**Custom** ではより限定された範囲を選択でき、少なくとも 1 つの 権限 を選択してください。付与できるのは、自分が保有している 権限 のみです。

## 組織 キーを作成する [#create-organization-keys]

**組織 &gt; Developer &gt; API キー** から 組織 キーを作成します。組織 キーでは `gtx-org-` プレフィックスを使用し、カスタムの権限セットを設定できます。

これらの Dashboard のコントロールでは、権限はリソースごとに設定されます。`Write` には `Read` が含まれます。

| Resource                | 読み取り                | 書き込み or enabled                              |
| ----------------------- | ------------------- | -------------------------------------------- |
| **プロジェクトの作成**           | 該当なし                | 組織 内に新しいプロジェクトを作成する                          |
| **プロジェクトの API キー**      | プロジェクトの API キーを表示する | プロジェクトの API キーを表示・作成・削除する                    |
| **ファイル**                | プロジェクトのファイルと翻訳を読み取る | ソースコンテンツをアップロードし、翻訳済みファイルを書き込む               |
| **文脈**                  | プロジェクトと 組織 の文脈を読み取る | コンテキストグループ、用語集、カスタムプロンプトを管理する                  |
| **組織 アセット**             | 該当なし                | 組織 内のすべてのプロジェクトで共有されるフォントなどのアセットをアップロード・置換する |
| **Runtime translation** | 該当なし                | オンデマンドでコンテンツを翻訳する                            |
| **Translation queue**   | 該当なし                | バックグラウンド処理のためにファイル翻訳ジョブをキューに追加する             |
| **プロジェクト設定**            | 該当なし                | デフォルトロケールや CDN 配信などのプロジェクト設定を更新する            |

[プロジェクトを作成](/docs/platform/openapi/reference/projects/create-project) エンドポイントを呼び出す自動化では、**プロジェクトの作成** を有効にしてください。この `org:projects:create` 権限があれば、CDN 配信を有効にした状態でプロジェクトを作成することもできます。**プロジェクト設定** (`project:write`) が必要になるのは、作成後に設定を更新する場合のみです。各キーには、必要な権限だけを付与してください。

[文脈 Management API](/docs/platform/openapi/reference/context-groups/list-context-groups) を呼び出す自動化では、**文脈** を **読み取り** または **書き込み** に設定してください (`org:context:read` / `org:context:write`)。この権限を持つ 組織 キーは、組織 内のすべての コンテキストグループ を操作できます。[プロジェクトキー](#create-project-keys)がアクセスできるのは、そのプロジェクトに割り当てられたグループのみです。また、グループの作成・更新・削除・割り当て・割り当て解除は行えません。

CLI の [`fonts`](/docs/cli/reference/config#fonts) 同期など、Lottie 翻訳用のフォントをアップロードする自動化では、**組織 アセット** を **書き込み** に設定してください (`org:assets:write`)。プロジェクトキーではフォントをアップロードできません。

[プロジェクトの API キーを作成](/docs/platform/openapi/reference/api-keys/create-project-api-key) または [プロジェクトの API キーを削除](/docs/platform/openapi/reference/api-keys/delete-project-api-key) を呼び出す自動化では、**プロジェクトの API キー** を **書き込み** に設定してください。プロジェクトのキーを[一覧表示](/docs/platform/openapi/reference/api-keys/list-project-api-keys)または[取得](/docs/platform/openapi/reference/api-keys/get-project-api-key)するだけであれば **読み取り** で十分です。これらの操作でシークレットが返されることはありません。その 組織 内のプロジェクトに対して必要な権限を持つ 組織 キーを使用してください。プロジェクトキーでは、キーの一覧表示・作成・削除はできません。

[HTTP API](/docs/platform/openapi/reference/api-keys/create-project-api-key) を通じてキーを作成する場合は、権限を明示的に選択してください。選択を省略すると、委任可能なすべてのプロジェクト権限が付与されます。Dashboard のコントロールとは異なり、HTTP で明示的に付与した 書き込み 権限には 読み取り は含まれません。

## プロジェクトキーを作成する [#create-project-keys]

プロジェクトキーは **プロジェクト &gt; API キー** から作成します。新しいキーは `gtx-api-` で始まり、development、ステージング、本番環境 のいずれの環境でも利用できます。実行できる操作は、そのキーの権限によって決まります。

1. キーを作成し、分かりやすい **Name** を入力します。
2. **権限** で **All** または **Custom** を選択します。
3. **Custom** の場合は、各リソースに必要なアクセス権を選択します。
4. **Create** を選択し、すぐにキー全体をコピーします。環境変数またはシークレットマネージャーに保存してください。

プロジェクトキーは次のリソースに対応しています:

| リソース                    | 読み取り                          | 書き込みまたは有効化                               |
| ----------------------- | ----------------------------- | ---------------------------------------- |
| **ファイル**                | プロジェクトのファイルと翻訳を読み取る           | ソースコンテンツをアップロードし、翻訳済みファイルを書き込む           |
| **文脈**                  | プロジェクトに割り当てられたコンテキストグループを読み取る | 文脈を生成し、プロジェクトに割り当てられたコンテキストグループを編集・並べ替える |
| **Runtime translation** | 該当なし                          | コンテンツをオンデマンドで翻訳する                        |
| **Translation queue**   | 該当なし                          | ファイルの翻訳ジョブをキューに追加する                      |
| **プロジェクト設定**            | 該当なし                          | プロジェクト設定を更新する                            |

**文脈** の権限があれば、プロジェクトキーは自身のプロジェクトに割り当てられたコンテキストグループに対して [Context Management API](/docs/platform/openapi/reference/context-groups/list-context-groups) を呼び出せます。**読み取り** (`project:context:read`) では、それらのグループの一覧表示と、各グループの用語集およびカスタムプロンプトの読み取り・エクスポートができます。**書き込み** (`project:context:write`) では、これに加えて内容の編集とインポート、グループの並べ替え、文脈の生成も行えます。プロジェクトキーでは、コンテキストグループの作成、更新、削除、割り当て、割り当て解除はできません。これらの操作には組織キーが必要です。キーのプロジェクトに割り当てられていないグループを指定した場合も、存在しないグループと同じく `403` が返されます。

ローカルでのオンデマンド翻訳には、`project:translations:generate` を持つプロジェクトキーであればどれでも使用でき、フルアクセスのキーでも構いません。リスクを最小限に抑えるため、**Custom** 権限の専用キーを用意することを推奨します。**Runtime translation** を **Enabled** に設定し、他のリソースは **None** のままにします。ファイル翻訳のパイプラインでは、**ファイル &gt; 書き込み** (読み取り を含みます)、**Translation queue &gt; Enabled**、**文脈 &gt; 書き込み** を付与します。[`gt translate`](/docs/cli/reference/commands/translate) は翻訳をキューに追加する前に文脈を生成するため、**文脈 &gt; 書き込み** がないと失敗します。なお、HTTP API または [`gt api-key create`](/docs/cli/reference/commands/api-key-create) でキーを作成する場合は、書き込み に 読み取り が含まれないため、`project:files:read`、`project:files:write`、`project:translations:enqueue`、`project:context:write` を明示的に指定してください。

SDK の設定 `devApiKey` と環境変数 `GT_DEV_API_KEY` は、引き続き開発時の翻訳とホットリロードを有効にします。この設定には、runtime translation 権限を持つプロジェクトキーを指定してください。なお、設定名は別の種類のキーを示すものではありません。

ほとんどの SDK および CLI のワークフローでは、キーをプロジェクト ID と組み合わせて使用します:

```bash
GT_API_KEY=gtx-api-...
GT_PROJECT_ID=...
```

アカウントベースで CLI を利用する場合は、[`gt login`](/docs/cli/reference/commands/login) を使用します。CLI から権限を明示的に指定したプロジェクトキーを作成するには、[`gt api-key create`](/docs/cli/reference/commands/api-key-create) を使用します。

## キーを管理する [#manage-keys]

後から見分けやすいように、キーにはわかりやすい名前を付けてください。

既存のキーを確認するには、プロジェクト または 組織 のキー一覧を開きます。キー一覧には次の項目が表示されます。

* **Name** と **Key** (識別しやすいように短縮表示されたキーを含む)
* **権限** (プロジェクトのキーと 組織キー の両方)
* **Created**、キーが生成された日時
* **Last Used**、キーが最後に使用された日時

キーを管理する権限がある場合は、**Edit key** でキーの名前を変更したり、権限を更新したりでき、**Delete** で失効できます。完全なシークレットはキーの作成時にのみ表示されます。

使われなくなったキーは失効し、認証情報をローテーションする際は置き換え用のキーを作成してください。削除したキーは通常すぐに認証できなくなり、遅くとも 10 分以内には無効になります。

自動化の中でプロジェクトキーをローテーションするには、置き換え用のキーを[作成](/docs/platform/openapi/reference/api-keys/create-project-api-key)してワークフローをそのキーに切り替えたうえで、古いキーを ID 指定で[削除](/docs/platform/openapi/reference/api-keys/delete-project-api-key)します。どちらの呼び出しにも、**プロジェクトの API キー** が **書き込み** に設定された組織キーが必要です。

## 既存の開発用キー [#existing-keys]

既存の `gtx-dev-` キーは、引き続きプロジェクトキーとして認証されます。従来のデフォルトであった runtime 専用権限のキーには、ファイル、context、Translation queue、プロジェクト設定を含むデフォルトのプロジェクト権限が付与されるようになりました。その他のカスタム権限セットはそのまま保持されます。

既存のキーは **プロジェクト &gt; API キー** で確認してください。ローカル開発では、**Runtime translation** のみに制限するか、新しい runtime 専用キーに置き換えることを推奨します。フルアクセスのキーも引き続き利用できますが、`gtx-dev-` プレフィックスが権限の制限を意味することはなくなりました。これらのキーは、デプロイするクライアントバンドルには絶対に含めないでください。

## セキュリティのベストプラクティス [#security-practices]

* キーをソース管理にコミットしないでください。
* 権限にかかわらず、デプロイされるブラウザまたはモバイルアプリのバンドルに API キーを含めないでください。デプロイ環境の認証情報は、サーバーサイドの環境変数またはシークレットマネージャーに保管してください。
* API キーは、ローカルの開発サーバーからのみ配信されるクライアントコードで使用できます。フルアクセスのプロジェクトキーでも動作しますが、リスクを最小限に抑えるため、ローカル開発用キーは **Runtime translation**(`project:translations:generate`)に制限することを推奨します。
* キーは環境変数またはシークレットマネージャーに保存してください。
* 開発、ステージング、本番環境ではそれぞれ別のキーを使用してください。
* キーは定期的にローテーションしてください。
* 不要なキーは失効させてください。
* 連携に必要な範囲で、できるだけ限定的なスコープを選んでください。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
