v3 API 概要 (ベータ)

v3 API は、サービスユーザー認証付きのフル RBAC サポートを提供します。本番環境での自動化には、この API の利用を推奨します。

v3 API は現在ベータ版です。API の改善に伴い、一部のエンドポイントは変更される可能性があります。

ベース URL:

https://api.devin.ai/v3beta1/enterprise/* – エンタープライズレベルの権限が必要なエンドポイント
https://api.devin.ai/v3beta1/organizations/* – 単一の組織を対象とするエンドポイント

認証方式: サービスユーザーの認証情報（エンタープライズまたは組織レベル） (詳細はこちら)

一部のエンタープライズエンドポイントは特定の組織を対象としますが、それでもエンタープライズレベルの権限で保護されています。これらは /v3beta1/enterprise/organizations/{org_id}/... のようなパスを使用します（例: GET /v3beta1/enterprise/organizations/{org_id}/audit-logs）。 org_id パスパラメータを含んでいても、ManageEnterpriseSettings のようなエンタープライズレベルの権限が引き続き必要です。

権限とRBAC

すべてのv3エンドポイントは、呼び出し元のサービスユーザーのロールに割り当てられた特定の権限によって制御されています。権限には2つのスコープがあります。Enterpriseレベルの権限は /v3beta1/enterprise/* エンドポイントを制御し、組織レベルの権限は /v3beta1/organizations/{org_id}/* エンドポイントを制御します。Enterpriseレベルの権限を持つ Enterprise サービスユーザーは、すべての組織に対して対応する組織レベルの権限を自動的に継承します。

Enterprise 権限

Permission	制御対象
`ReadAccountMeta`	自分自身（デフォルトですべてのサービスユーザーに付与）
`ManageEnterpriseSettings`	監査ログ、Organization タグ
`ManageOrganizations`	Organization の CRUD、Organization グループ数の上限
`ManageAccountMembership`	ロール、Enterprise ユーザー、Enterprise IdP グループ、Enterprise サービスユーザーのメンバーシップ、Enterprise IdP グループ登録
`ManageAccountServiceUsers`	サービスユーザーのプロビジョニング（Enterprise）
`ManageAccountKnowledge`	Knowledge ノート（Enterprise）
`ManageAccountPlaybooks`	Playbook（Enterprise）
`ManageGitIntegrations`	Git 接続、Git 権限
`ManageBilling`	利用サイクル、日次の利用内訳
`ViewAccountMetrics`	利用状況メトリクス（DAU/WAU/MAU、PR（プルリクエスト）、セッション、検索、アクティブユーザー）、キューのステータス
`ViewEnterpriseInfraDetails`	ハイパーバイザー
`ViewAccountSessions`	セッションの一覧と詳細（Enterprise、読み取り専用）
`ManageAccountSessions`	セッションへのメッセージの送信（Enterprise）
`ViewAccountSearches`	検索（Enterprise）

組織権限

Permission	Controls
`ManageOrgSecrets`	シークレットの CRUD
`ManageOrgKnowledge`	Knowledge ノート（組織）
`ManageOrgPlaybooks`	Playbook（組織）
`ManageOrgServiceUsers`	サービスユーザーのプロビジョニング（組織）
`ViewOrgSessions`	セッションの一覧および詳細（組織、読み取り専用）
`ManageOrgSessions`	メッセージの送信、セッションの終了およびアーカイブ
`UseDevinSessions`	セッションの作成
`ImpersonateOrgSessions`	他のユーザーになり代わってセッションを作成（`create_as_user_id`）
`ViewOrgSearches`	検索（組織）

サービスユーザーのスコープ

Enterprise サービスユーザー は /v3beta1/enterprise/* エンドポイントで認証を行い、すべての組織をまたいで操作できます。Enterprise レベルのロールが割り当てられ、各ロールに対応する組織レベルの権限を、すべての組織で自動的に継承します（たとえば、ViewAccountSessions はすべての組織で ViewOrgSessions を付与します）。 Organization サービスユーザー は単一の組織のみにスコープが限定され、/v3beta1/organizations/{org_id}/* エンドポイントでのみ認証されます。これらのユーザーには組織レベルのロールが割り当てられます。

サービスユーザーの作成

サービスユーザーは次の 2 通りの方法で作成できます。

UI: Enterprise Settings → Service Users — カスタムロールを指定して Enterprise または組織レベルのサービスユーザーを作成し、API トークンを生成します。
API: POST /v3beta1/enterprise/service-users または POST /v3beta1/organizations/{org_id}/service-users — 指定したロールと TTL を用いて、プログラムからサービスユーザーをプロビジョニングします。新しいユーザーの権限は必ず呼び出し元ユーザーの権限のサブセットである必要があります（特権昇格は許可されません）。

トークン生成および認証の詳細については、Authentication Guide を参照してください。