> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 認証

> プリンシパルとトークン、そして Devin API で認証する方法を理解する

Devin API は、**プリンシパル + トークン**モデルを利用します。**プリンシパル**は「誰であるか」 (ID) を表し、**トークン**はそれをどのように証明するか (認証情報) を表します。この違いを理解することが、ユースケースに適した認証方法を選ぶための鍵となります。

<div id="principals-tokens">
  ## プリンシパル & トークン
</div>

| プリンシパル              | トークン                | 説明                          |
| ------------------- | ------------------- | --------------------------- |
| **サービスユーザー** (人間以外) | サービスユーザー APIキー      | 自動化された統合および CI/CD パイプライン向け  |
| **ユーザー** (人間)       | パーソナルアクセストークン (PAT) | ご自身のユーザーIDで行うプログラムからのアクセス向け |

すべてのAPI認証情報は `cog_` で始まります。すべてのリクエストの `Authorization` ヘッダーにトークンを含めてください。

```bash theme={null}
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer cog_your_token_here"
```

重要な違いは、**トークンがどの主体として認証されるか**です。

* **Service User API Key** は **サービスユーザー** として認証されます。つまり、サービスユーザーのアイデンティティ、権限、orgへの所属が適用されます。
* **パーソナルアクセストークン** は、それを作成した **人間のユーザー** として認証されます。つまり、そのユーザーのアイデンティティ、権限、orgへの所属が適用されます。

***

<div id="service-users-recommended-for-automation">
  ## サービスユーザー (自動化に推奨)
</div>

サービスユーザーは、API 統合向けに設計された人間以外のアカウントです。RBAC を通じて特定の権限を割り当てることができ、人間のユーザーとは別に組織へ追加できます。

<div id="how-it-works">
  ### 仕組み
</div>

1. **Settings > Service users** (組織) または **Enterprise settings > Service users** (Enterprise) で **サービスユーザーを作成** します
2. サービスユーザーがアクセスできるエンドポイントを制御する **ロールを割り当て** ます
3. **APIキーを生成** します — キーは `cog_` で始まり、作成時に一度だけ表示されます
4. すべての API リクエストの `Authorization` ヘッダーに **このキーを含め** ます

```bash theme={null}
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a simple Python script"}'
```

<div id="service-user-scopes">
  ### サービスユーザーのスコープ
</div>

| スコープ             | 作成場所                                | API アクセス                                   | ユースケース                          |
| ---------------- | ----------------------------------- | ------------------------------------------ | ------------------------------- |
| **Organization** | Settings > Service users            | `/v3/organizations/*`                      | セッション管理、Knowledge、プレイブック、シークレット |
| **Enterprise**   | Enterprise settings > Service users | `/v3/enterprise/*` + `/v3/organizations/*` | 組織横断の管理、分析、監査ログ、請求              |

<Tip>
  **Settings > Service Users** ページで organization ID を確認してください。
</Tip>

<div id="session-attribution-with-create_as_user_id">
  ### `create_as_user_id` を使ったセッションの帰属
</div>

サービスユーザーは、人間のユーザーとは別個の ID です。デフォルトでは、サービスユーザーによって作成されたセッションは、そのサービスユーザー自身に帰属します。特定のユーザー **の代わりにセッションを作成する** 場合は、セッション作成時に `create_as_user_id` パラメータを指定します。セッションはそのユーザーのセッション一覧に表示され、そのユーザーの使用量としてカウントされます。

これには、サービスユーザーのロールに `ImpersonateOrgSessions` 権限が必要です。

<div id="key-properties">
  ### キーの主なプロパティ
</div>

* キーは `cog_` で始まり、作成時に一度だけ表示されます
* サービスユーザーは、監査ログ上で人間のユーザーとは別に表示されます
* 権限は RBAC で制御されます — 連携に必要なものだけを付与してください
* Enterprise のサービスユーザーは、すべての組織にわたって org レベルの権限を継承します

詳細なセットアップ手順については、[Teams クイックスタート](/ja/api-reference/getting-started/teams-quickstart) または [Enterprise クイックスタート](/ja/api-reference/getting-started/enterprise-quickstart) を参照してください。

***

<div id="personal-access-tokens-closed-beta">
  ## パーソナルアクセストークン (クローズドベータ)
</div>

<Note>
  パーソナルアクセストークンは現在**クローズドベータ**で、機能フラグで提供されています。アクセスをご希望の場合は、[サポートにお問い合わせください](mailto:support@cognition.ai)。PAT は SSO (シングルサインオン) /Enterprise アカウントでは利用できません。
</Note>

パーソナルアクセストークン (PAT) を利用すると、ユーザーは自身の ID でプログラムから認証できます。PAT を利用すると、API からは **あなた自身** として認識されます。つまり、あなたの権限、org への所属、監査証跡が適用されます。

これは、共有のサービスユーザー経由ではなく、自分自身として APIコール を行いたい場合 (たとえば、個人用スクリプトやローカルツール) に便利です。

詳細については、[パーソナルアクセストークン](/ja/api-reference/personal-access-tokens)を参照してください。

***

<div id="legacy-authentication-deprecated">
  ## レガシー認証 (非推奨)
</div>

<Warning>
  レガシー API キーは非推奨です。サービスユーザー認証で [API v3](/ja/api-reference/v3/overview) を利用してください。[移行ガイド](/ja/api-reference/getting-started/migration-guide)を参照してください。
</Warning>

レガシー API キーは v1 および v2 API で使用されます。非推奨期間中は引き続き利用できますが、RBAC、セッションのアトリビューション、カーソルベースのページネーションといった新機能には対応していません。

| Key type             | Prefix      | Used with | Description                   |
| -------------------- | ----------- | --------- | ----------------------------- |
| **Personal API key** | `apk_user_` | v1, v2    | ユーザーアカウントに紐づき、そのユーザーの権限を継承します |
| **Service API key**  | `apk_`      | v1        | 組織スコープで、自動化用途向け               |

**発行場所:** [Settings > API Keys](https://app.devin.ai/settings/api-keys)

***

<div id="security-best-practices">
  ## セキュリティのベストプラクティス
</div>

<Warning>
  GitHub リポジトリ、クライアントサイドのコード、ログなど、公開されている場所で APIキーを決して共有しないでください。
</Warning>

1. **キーを安全に保管する**: 環境変数やシークレット管理システムを使用する
2. **キーを定期的にローテーションする**: 定期的に新しいキーを発行し、古いキーを失効させる
3. **自動化にはサービスユーザーを使用する**: 本番環境では個人のキーではなくサービスユーザーを優先して使用する
4. **最小権限の原則を適用する**: 必要最小限の権限のみを付与する
5. **利用状況を監視する**: 予期しない API の利用がないか監査ログを確認する
6. **漏えいしたキーは直ちに失効させる**: キーが漏えいした場合は、そのキーを失効させて新しいキーを発行する

<div id="troubleshooting">
  ## トラブルシューティング
</div>

<div id="401-unauthorized">
  ### 401 Unauthorized
</div>

**考えられる原因:**

* 無効または期限切れの APIキー
* `Authorization` ヘッダーが設定されていない
* Bearer トークン形式の誤り
* [Devin MCP](/ja/work-with-devin/devin-mcp) でレガシー APIキー (`apk_` / `apk_user_`) を利用している — `cog_` プレフィックスのキーのみがサポートされています

**解決策:** APIキー が有効であり、Authorization ヘッダーに正しい形式で設定されていることを確認してください。MCP の使用では、サービスユーザー APIキー (レガシーキーではないもの) を利用していることを確認してください。

<div id="403-forbidden">
  ### 403 Forbidden
</div>

**考えられる原因:**

* API key に必要な権限が付与されていない
* エンドポイントに対して誤ったキー種別を使用している (例: v3 エンドポイントに legacy key を使用している)
* 許可スコープ外のリソースへアクセスしようとしている

**解決策:**

* service user に正しいロールと権限が付与されていることを確認する
* legacy v2 エンドポイントの場合: Enterprise Admin ロールを持っていることを確認する
* legacy v1 エンドポイントの場合: 対象の組織 (organization) へのアクセス権があることを確認する

<div id="404-not-found">
  ### 404 Not Found
</div>

**考えられる原因：**

* API エンドポイント URL が正しくない
* リソースが存在しない、またはアクセス権限がない

**解決方法：** エンドポイント URL とリソースの存在を確認してください。

<div id="next-steps">
  ## 次のステップ
</div>

* [Teams クイックスタート](/ja/api-reference/getting-started/teams-quickstart) — 数分で利用開始
* [Enterprise クイックスタート](/ja/api-reference/getting-started/enterprise-quickstart) — RBAC と複数組織環境のセットアップ
* [一般的なフロー](/ja/api-reference/common-flows) — エンドツーエンドのワークフロー使用例
* [移行ガイド](/ja/api-reference/getting-started/migration-guide) — v1/v2 からの移行