# 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 つの 権限 を選択してください。付与できるのは、自分が保有している 権限 のみです。

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

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

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

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

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

[Context Management API](/docs/platform/openapi/reference/context-management/list-groups) を呼び出す自動化では、**Context** を **Read** または **Write** に設定してください (`org:context:read` / `org:context:write`)。プロジェクトキーでは Context Group を管理できません。

[プロジェクトの API キーを作成](/docs/platform/openapi/reference/project/create-api-key) を呼び出す自動化では、**プロジェクトの API キー** を **Write** に設定してください。その Organization 内のプロジェクトに対して必要な権限を持つ Organization キーを使用してください。プロジェクトキーでは他のキーを作成できません。

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

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

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

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

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

| リソース                    | 読み取り                | 書き込みまたは有効化                     |
| ----------------------- | ------------------- | ------------------------------ |
| **Files**               | プロジェクトのファイルと翻訳を読み取る | ソースコンテンツをアップロードし、翻訳済みファイルを書き込む |
| **Context**             | プロジェクトのコンテキストを読み取る  | プロジェクトのコンテキストを管理する             |
| **Runtime translation** | 該当なし                | コンテンツをオンデマンドで翻訳する              |
| **Translation queue**   | 該当なし                | ファイルの翻訳ジョブをキューに追加する            |
| **プロジェクト設定**    | 該当なし                | プロジェクト設定を更新する                  |

ローカルでのオンデマンド翻訳には、`project:translations:generate` を持つプロジェクトキーであればどれでも使用でき、フルアクセスのキーでも構いません。リスクを最小限に抑えるため、**Custom** 権限の専用キーを用意することを推奨します。**Runtime translation** を **Enabled** に設定し、他のリソースは **None** のままにします。ファイル翻訳のパイプラインでは、**Files > Write** と **Translation queue > Enabled** を付与し、パイプラインがコンテキストを生成する場合は **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]

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

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

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

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

使われなくなったキーは失効し、認証情報をローテーションする際は置き換え用のキーを作成してください。

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

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

既存のキーは **プロジェクト > 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.