サービスユーザーは、ロールベースの権限を持つ API アクセス専用のボットアカウントです。これは、すべての新規連携に対して推奨される認証方法です。
- Settings > Service users でサービスユーザーを作成します
- サービスユーザーがアクセスできるエンドポイントを制御するロールを割り当てます
cog_ で始まる APIキーを生成します- すべてのリクエストで
Authorization ヘッダーにこのキーを含めます
curl -X POST "https://api.devin.ai/v3/organizations/sessions" \
-H "Authorization: Bearer $DEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a simple Python script"}'
| スコープ | 作成場所 | API アクセス | ユースケース |
|---|
| Organization | Settings > Service users | /v3/organizations/* | セッション管理、Knowledge、プレイブック、シークレット |
| Enterprise | Enterprise settings > Service users | /v3/enterprise/* + /v3/organizations/* | 組織横断の管理、分析、監査ログ、請求 |
Organization スコープのサービスユーザーは、URL で {org_id} を指定しなくてもエンドポイントを呼び出せます。{org_id} は認証情報から自動的に解決されます。
create_as_user_id を使ったセッションの帰属
create_as_user_id パラメータを指定します。セッションはそのユーザーのセッション一覧に表示され、そのユーザーの使用量としてカウントされます。
これには、サービスユーザーのロールに ImpersonateOrgSessions 権限が必要です。
個人の APIキー から移行しますか？ 個人の APIキー (v1/v2) は、あなたのユーザーとして自動的にセッションを作成していました。サービスユーザーを使う場合は、同じ動作を実現するために create_as_user_id を使用します。さらに RBAC や監査ログ、キー管理の一元化も利用できます。例については API Overview を参照してください。
- キーは
cog_ で始まり、作成時に一度だけ表示されます
- サービスユーザーは、監査ログ上で人間のユーザーとは別に表示されます
- 権限は RBAC で制御されます — 連携に必要なものだけを付与してください
- Enterprise のサービスユーザーは、すべての組織にわたって org レベルの権限を継承します
詳細なセットアップ手順については、Teams クイックスタート または Enterprise クイックスタート を参照してください。
レガシー API キーは、サービスユーザーへの移行を前提として廃止予定です。既存の連携については、サービスユーザーへの移行を推奨します。移行ガイドを参照してください。 | Key type | Prefix | Used with | Description |
|---|
| Personal API key | apk_user_ | v1, v2 | ユーザーアカウントに紐づき、そのユーザーの権限を継承します |
| Service API key | apk_ | v1 | 組織スコープで、自動化用途向け |
すべての Devin API は Bearer トークン認証を利用します。Authorization ヘッダーにキーを指定してください。
Authorization: Bearer your_api_key_here
GitHub リポジトリ、クライアントサイドのコード、ログなど、公開されている場所で APIキーを決して共有しないでください。
- キーを安全に保管する: 環境変数やシークレット管理システムを使用する
- キーを定期的にローテーションする: 定期的に新しいキーを発行し、古いキーを失効させる
- 自動化にはサービスユーザーを使用する: 本番環境では個人のキーではなくサービスユーザーを優先して使用する
- 最小権限の原則を適用する: 必要最小限の権限のみを付与する
- 利用状況を監視する: 予期しない API の利用がないか監査ログを確認する
- 漏えいしたキーは直ちに失効させる: キーが漏えいした場合は、そのキーを失効させて新しいキーを発行する
考えられる原因:
- 無効または期限切れの APIキー
Authorization ヘッダーが設定されていない- Bearer トークン形式の誤り
解決策: APIキー が有効であり、Authorization ヘッダーに正しい形式で設定されていることを確認してください。
考えられる原因:
- API key に必要な権限が付与されていない
- エンドポイントに対して誤ったキー種別を使用している（例: v3 エンドポイントに legacy key を使用している）
- 許可スコープ外のリソースへアクセスしようとしている
解決策:
- service user に正しいロールと権限が付与されていることを確認する
- legacy v2 エンドポイントの場合: Enterprise Admin ロールを持っていることを確認する
- legacy v1 エンドポイントの場合: 対象の組織（organization）へのアクセス権があることを確認する
考えられる原因：
- API エンドポイント URL が正しくない
- リソースが存在しない、またはアクセス権限がない
解決方法： エンドポイント URL とリソースの存在を確認してください。
