Devin では、認証メカニズムや認可モデルが異なる複数の API バージョンを提供しています。どの種類の APIキーを使用すべきかを理解することは、適切な統合のために不可欠です。
| Version | 認証方式 | 認可モデル |
|---|
| v1 | 個人用またはサービス用APIキー | 組織スコープ |
| v2 | 個人用APIキー | Enterprise管理者のみ |
| v3 (Beta) | サービスユーザー資格情報 | 完全なRBAC |
| APIキーの種類 | プレフィックス | 説明 |
|---|
| パーソナルAPIキー | apk_user_ | 個々のユーザー権限を継承するユーザーおよび組織スコープのキー |
| サービスAPIキー | apk_ | 自動化用の組織スコープのサービスキー |
| サービスユーザー資格情報 | cog_ | RBAC 対応の Enterprise/組織向けサービスユーザー資格情報 |
- 任意のサブ組織で Settings > API Keys に移動します
- 「Generate New API Key」をクリックします
- キーをコピーして安全な場所に保管します（キーは一度しか表示されません）
対応している API バージョン:
- v1: 対応 - ユーザーの組織レベルの権限を継承します
- v2: 対応 - Enterprise Admin ロールを持つユーザーのみ利用可能
- v3: 非対応 - 代わりに Service User 資格情報を使用してください
推奨ユースケース:
- 個人用自動化スクリプト
- 開発およびテスト
- ユーザー固有の連携（インテグレーション）
セキュリティ上の考慮事項:
- キーは、そのユーザーに付与されている権限の範囲にスコープされます
- ユーザーのアクセスを取り消すと、そのユーザーの API キーは自動的に無効になります
- キーは定期的にローテーションする必要があります
サービスAPIキーは、特定の条件を満たすサブ組織内で作成できます。
作成場所:
対応している API バージョン:
- v1: はい - 組織スコープで利用可能
- v2: いいえ - 未対応
- v3: いいえ - 代わりに Service User Credentials を使用してください
推奨ユースケース:
- 組織レベルの自動化
- 特定のチームをスコープとした CI/CD パイプライン
- サブ組織内での共通ツール
サービスユーザーは、特定のロールと権限を持つ専用アカウントであり、RBAC をフルサポートした API ベースの自動化向けに設計されています。
作成場所:
サービスユーザーの種類:
- Enterprise Service Users: 割り当てられたロールに基づき、複数の組織にアクセスできます
- Organization Service Users: 特定の組織に限定され、その組織レベルのロールを持ちます
サポートされている API バージョン:
- v1: No - 利用不可
- v2: No - 利用不可
- v3: Yes - RBAC を完全サポート
推奨ユースケース:
- きめ細かい権限を必要とする本番環境の自動化
- 複数組織間のワークフロー
- 監査証跡を要するコンプライアンス重視の連携
- 特定の権限スコープを持つ長期運用の連携
セキュリティ上の考慮事項:
- サービスユーザーは、人間のユーザーとは別に監査ログに記録される
- 権限は RBAC により厳密に制御可能
- キーは人間のユーザーアカウントに影響を与えずにローテーションできます
- 最小権限の原則を実践するのに最適
すべての Devin API は Bearer トークン認証を利用します。Authorization ヘッダーに APIキー を指定してください。
Authorization: Bearer your_api_key_here
curl -X POST "https://api.devin.ai/v1/sessions" \
-H "Authorization: Bearer YOUR_V1_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "シンプルなPythonスクリプトを作成"
}'
curl -X GET "https://api.devin.ai/v2/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V2_ENTERPRISE_ADMIN_KEY"
curl -X GET "https://api.devin.ai/v3beta1/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V3_SERVICE_USER_KEY"
GitHub リポジトリ、クライアントサイドのコード、ログなど、公開されている場所で APIキーを決して共有しないでください。
- キーを安全に保管する: 環境変数やシークレット管理システムを使用する
- キーを定期的にローテーションする: 定期的に新しいキーを発行し、古いキーを失効させる
- 自動化にはサービスユーザーを使用する: 本番環境では個人のキーではなく v3 サービスユーザーを優先して使用する
- 最小権限の原則を適用する: 必要最小限の権限のみを付与する
- 利用状況を監視する: 予期しない API の利用がないか監査ログを確認する
- 漏えいしたキーは直ちに失効させる: キーが漏えいした場合は、そのキーを失効させて新しいキーを発行する
考えられる原因:
- 無効または期限切れの APIキー
Authorization ヘッダーが設定されていない- Bearer トークン形式の誤り
解決策: APIキー が有効であり、Authorization ヘッダーに正しい形式で設定されていることを確認してください。
考えられる原因:
- API key に必要な権限が付与されていない
- キー種別に対して誤った API バージョンを使用している（例: personal key で v3 を使用）
- 許可スコープ外のリソースへアクセスしようとしている
解決策:
- v2 の場合: Enterprise Admin ロールを持っていることを確認する
- v3 の場合: 適切なロールを持つ service user の認証情報を使用する
- v1 の場合: 対象の組織（organization）へのアクセス権があることを確認する
考えられる原因：
- API エンドポイント URL が正しくない
- リソースが存在しない、またはアクセス権限がない
解決方法： 使用している API バージョンにエンドポイント URL が対応していることと、リソースが存在することを確認してください。
