開発者ユーザーグラフと招待

対象読者：組織、プロジェクト、チームアクセスを設計する backend と console 開発者。

Alpha account の user_type は developer または system_admin です。developer は登録、ログイン、organization 作成、project 作成、Project Key 発行を行います。Project Key は Public API の GET /v1/sdk/config、POST /v1/feedback/reports、consent で制限された attachment route を使えますが、/admin/v1/* には access できません。account type と tenant authorization は独立しており、organization と project への access は常に membership によって決まります。

最小例

flowchart LR
  User["authenticated user"] --> UserType["user_type"]
  UserType --> Developer["developer"]
  UserType --> SystemAdmin["system_admin"]
  User --> OrgMembership["organization membership"]
  User --> ProjectMembership["project membership"]
  OrgMembership --> Organization["organization"]
  ProjectMembership --> Project["project"]
  Organization --> Project["project"]
  SystemAdmin --> SystemUsers["GET /admin/v1/system/users"]
  Project --> ProjectKey["Project Key"]
  ProjectKey --> PublicAPI["Public API SDK config / feedback write"]
  Project --> FeedbackReport["feedback_report"]

AdminUser contract の user_type は system_admin と developer、user status は active、disabled、pending_verification です。system administrator に追加される system-wide capability は read-only の /admin/v1/system/users だけです。これは tenant role ではなく、organization や project を自動的に公開しません。system administrator が tenant に参加した場合、response には実際の membership role が入り、membership がなければその tenant を指定した request は 403 になります。

Organization と Project response は membership role を必ず含み、値は owner、admin、developer、qa、viewer だけです。member account の user_type は developer または system_admin ですが、その role は変わりません。E2E matrix は developer A が org/project/key を作成し、developer B が招待で参加して project を読めること、developer C が拒否されることを検証します。

GET /admin/v1/developer-graph は current user と、visible organization、project、organization membership、direct project membership をまとめて返す navigation aggregate です。canonical list GET ではなく、limit/offset を受け取らず、{ items, offset, limit, total, has_more } envelope も使いません。個別の organization、project、member collection endpoint は pagination contract を使います。

招待は canonical Alpha management API の一部です。Developer Console は /admin/v1/organizations/{organization_id}/developer-invitations で organization invitation を作成・一覧化します。招待側は一度だけ表示される token のみをコピーし、credential を含む link は作りません。受信者は credential を含まない /invitations/accept を開き、必要なら login または register を済ませ、戻ったページで token を貼り付けます。token は現在の form 内だけに存在し、JSON body で /admin/v1/invitations/accept に送ります。URL、return_to、browser storage、log に入れてはいけません。

project_id がない招待は organization membership を作成し、developer graph の memberships に表示されます。project_id がある招待は project membership のみを作成し、project_memberships に表示されます。受諾した developer はその project、feedback、attachments、comments にアクセスできますが、organization detail は読めず、organization member list にも表示されません。

Organization-scoped invitation:

curl -X POST "$ADMIN_API/admin/v1/organizations/$ORG_ID/developer-invitations" \
  -H "Authorization: Bearer $TOKEN_A" \
  -H "Content-Type: application/json" \
  -d '{"email":"developer-b@example.com","role":"developer"}'

curl -X POST "$ADMIN_API/admin/v1/invitations/accept" \
  -H "Authorization: Bearer $TOKEN_B" \
  -H "Content-Type: application/json" \
  -d '{"token":"enb_inv_..."}'

Project-scoped invitation:

curl -X POST "$ADMIN_API/admin/v1/projects/$PROJECT_ID/invitations" \
  -H "Authorization: Bearer $TOKEN_A" \
  -H "Content-Type: application/json" \
  -d '{"email":"developer-d@example.com","role":"qa"}'

curl -X POST "$ADMIN_API/admin/v1/invitations/accept" \
  -H "Authorization: Bearer $TOKEN_D" \
  -H "Content-Type: application/json" \
  -d '{"token":"enb_inv_..."}'

project-scoped invitation を受諾した後、招待された developer は GET /admin/v1/projects/{project_id} にアクセスできますが、GET /admin/v1/organizations/{organization_id} は 403 になります。project invitation list と revoke response には accept_token を含めず、create response だけが一度だけ表示します。revoke response には revoked_by_user_id と revoked_at が含まれ、invitation audit metadata に token value を含めてはいけません。

Alpha verification matrix では Developer B を organization-scoped invitation、Developer D を project-scoped invitation、Developer C を denied user として検証します。

よくある間違い

project key に feedback 読み取りや user 管理を許可しないでください。
user_type に基づいて tenant membership check を迂回しないでください。
token を含む invitation URL を作らず、一度だけ表示される token と共通 /invitations/accept page を分けて共有してください。
invite token をログに保存したり list response で公開したりしないでください。
Developer Graph に pagination parameter を送ったり、list envelope として解析したりしないでください。

次のステップ

ローカル経路が動かない場合はトラブルシューティングを使ってください。