チームAPI

チームAPI

チームAPIを使用すると、組織のメンバーを管理できます。新しいコラボレーターの招待、ロールの割り当て、権限の更新、メンバーの削除が可能です。チームメンバーの上限はサブスクリプションプランに基づいて適用されます。

ベースURL: https://api.zenflip.io/v1/teams

ロールと権限

ZenFlipは階層的な権限を持つ4つのロールを使用します：

各組織にはownerが1名のみ存在します。ownerロールは削除も降格もできません。オーナーシップの移転はダッシュボードから行う必要があります。

チームメンバー一覧

組織のすべてのメンバーを取得します。

` GET /teams/members `

リクエスト例

`bash curl "https://api.zenflip.io/v1/teams/members" \ -H "Authorization: Bearer YOUR_TOKEN" `

レスポンス例

`json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "owner@example.com", "name": "Alex Chen", "role": "owner", "status": "active", "avatarUrl": "https://cdn.zenflip.io/avatars/550e8400.jpg", "emailVerified": true, "lastActiveAt": "2026-02-20T14:00:00.000Z", "createdAt": "2025-06-01T10:00:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "email": "editor@example.com", "name": "Sarah Kim", "role": "editor", "status": "active", "avatarUrl": null, "emailVerified": true, "lastActiveAt": "2026-02-19T16:30:00.000Z", "createdAt": "2025-09-15T08:00:00.000Z" }, { "id": "770e8400-e29b-41d4-a716-446655440002", "email": "newuser@example.com", "name": "Pending User", "role": "viewer", "status": "invited", "avatarUrl": null, "emailVerified": false, "lastActiveAt": null, "createdAt": "2026-02-18T11:00:00.000Z" } ] } `

statusフィールドは、メンバーがactive（招待を承認済み）かinvited（承認待ち）かを示します。

チームメンバーの招待

新しいチームメンバーにメール招待を送信します。招待された方はパスワードを設定し、組織に参加するためのリンクを受け取ります。

` POST /teams/invite `

必要なロール： admin以上。

リクエストボディ

リクエスト例

`bash curl -X POST "https://api.zenflip.io/v1/teams/invite" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "neweditor@example.com", "name": "Jordan Lee", "role": "editor" }' `

レスポンス例

`json { "data": { "id": "880e8400-e29b-41d4-a716-446655440003", "email": "neweditor@example.com", "name": "Jordan Lee", "role": "editor", "status": "invited", "createdAt": "2026-02-20T16:00:00.000Z" } } `

組織がプランのチームメンバー上限に達している場合、APIは上限に達したことを示すメッセージとともに403エラーを返します。

招待の再送信

保留中のチームメンバーに招待メールを再送信します。

` POST /teams/members/:id/resend-invite `

必要なロール： admin以上。

リクエスト例

`bash curl -X POST "https://api.zenflip.io/v1/teams/members/880e8400.../resend-invite" \ -H "Authorization: Bearer YOUR_TOKEN" `

レスポンス例

`json { "message": "Invitation resent" } `

招待の取り消し

承認前の保留中の招待をキャンセルします。

` DELETE /teams/members/:id/revoke-invite `

必要なロール： admin以上。

リクエスト例

`bash curl -X DELETE "https://api.zenflip.io/v1/teams/members/880e8400.../revoke-invite" \ -H "Authorization: Bearer YOUR_TOKEN" `

レスポンス例

`json { "message": "Invitation revoked" } `

招待の検証（パブリック）

招待トークンが有効かどうかを、トークンを消費せずに確認します。これはフロントエンドが招待承認フォームを表示するために使用するパブリックエンドポイントです。

` POST /teams/validate-invite `

認証不要。

リクエストボディ

レスポンス例

`json { "data": { "valid": true, "email": "neweditor@example.com", "organizationName": "Acme Publishing", "role": "editor", "invitedBy": "Alex Chen" } } `

招待の承認（パブリック）

招待を承認してパスワードを設定します。このエンドポイントはユーザーアカウントを作成し、JWTトークンを生成し、ユーザーを即座にログインさせます。

` POST /teams/accept-invite `

認証不要。

リクエストボディ

リクエスト例

`bash curl -X POST "https://api.zenflip.io/v1/teams/accept-invite" \ -H "Content-Type: application/json" \ -d '{ "token": "invite_token_abc123", "password": "SecureP@ssw0rd!" }' `

レスポンス例

`json { "message": "Invitation accepted successfully", "user": { "id": "880e8400-e29b-41d4-a716-446655440003", "email": "neweditor@example.com", "name": "Jordan Lee", "role": "editor" }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Acme Publishing" }, "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600 } `

メンバーロールの更新

既存のチームメンバーのロールを変更します。

` PATCH /teams/members/:id/role `

必要なロール： admin以上。

リクエストボディ

リクエスト例

`bash curl -X PATCH "https://api.zenflip.io/v1/teams/members/660e8400.../role" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "role": "admin" }' `

レスポンス例

`json { "data": { "id": "660e8400-e29b-41d4-a716-446655440001", "email": "editor@example.com", "name": "Sarah Kim", "role": "admin", "status": "active" } } `

制限事項：

• ownerロールは変更できません。

• adminは他のメンバーをownerに昇格できません。

• 自分自身のロールは変更できません。

チームメンバーの削除

組織からメンバーを削除します。すべてのアクセス権が即座に取り消されます。

` DELETE /teams/members/:id `

必要なロール： admin以上。

リクエスト例

`bash curl -X DELETE "https://api.zenflip.io/v1/teams/members/660e8400-e29b-41d4-a716-446655440001" \ -H "Authorization: Bearer YOUR_TOKEN" `

レスポンス例

`json { "message": "Team member removed" } `

制限事項：

• 組織のownerは削除できません。

• メンバーは自分自身を削除できません（組織からの退出はダッシュボードから行ってください）。

プラン上限

チームメンバーの上限はサブスクリプションプランによって異なります：

プラン上限を超えてメンバーを招待しようとすると、403エラーが返されます。上限を引き上げるには、請求設定からプランをアップグレードしてください。