メンバー API

チームシートと役割を管理します——アカウントの発行者、バッジ、授与を共有する人々です。

すべてのエンドポイントは認証を必要とします。認証を参照してください。すべてのリクエストは、認証されたオーナーのアカウントにスコープされます。

API で割り当てられる役割は admin、editor、viewer です。owner の役割はアカウント保有者用に予約されており、割り当てや削除はできません。

メンバー一覧の取得

アカウント上のすべてのメンバーと保留中の招待を取得します。

GET /members

例

curl -X GET https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here"

レスポンス

{
  "items": [
    {
      "memberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "owner@acme.example.com",
      "role": "owner",
      "status": "active"
    },
    {
      "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "email": "editor@acme.example.com",
      "role": "editor",
      "status": "pending"
    }
  ]
}

status は、承認済みのメンバーの場合は active、まだ承認されていない招待の場合は pending です。

---

メンバーの招待

メールでアカウントに人を招待します。承認リンク付きの招待メールがそのアドレスに送信されます。

POST /members

パラメータ

パラメータ	型	必須	説明
email	string	はい	招待するメールアドレス（有効なメールである必要があります）
role	string	はい	割り当てる役割——admin、editor、viewer のいずれか

例

curl -X POST https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "email": "editor@acme.example.com",
      "role": "editor"
    }
  }'

レスポンス

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "pending"
}

エラー

• 400 — role must be one of admin, editor, viewer
• 400 — メールアドレスが無効または欠落している
• 400 — seat limit reached — アカウントにプランの空きシートがありません（Free：2、Starter：5、Pro：20、オーナーを含む）。メンバーを削除するか、プランをアップグレードしてください。
• 400 — そのメールはすでにこのアカウントのメンバーであるか、保留中の招待があります

---

招待の承認

保留中の招待を承認します。認証されたユーザーのメールは、招待の送信先アドレスと一致している必要があります。

POST /members/accept

パラメータ

パラメータ	型	必須	説明
inviteId	string	はい	承認リンクメールに記載された招待 ID

例

curl -X POST https://api.badges.ninja/members/accept \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }
  }'

レスポンス

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "active"
}

エラー

• 400 — email does not match invitation — サインインしたメールが招待されたメールと異なる
• 404 — 招待が見つからない（すでに承認済み、キャンセル済み、または inviteId が誤っている）

---

メンバーの役割の更新

既存メンバーの役割を変更します。オーナーまたは管理者の権限が必要です。

POST /members/{memberId}/role

パラメータ

パラメータ	型	必須	説明
memberId	string	はい	メンバー ID（パスパラメータ）
role	string	はい	新しい役割——admin、editor、viewer のいずれか

例

curl -X POST https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901/role \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "role": "admin"
    }
  }'

レスポンス

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "role": "admin",
  "updated": true
}

エラー

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — メンバーが見つからない

---

メンバーの削除

メンバーをアカウントから削除するか、保留中の招待をキャンセルします。メンバーは直ちにアクセス権を失い、そのシートは解放されます。

DELETE /members/{memberId}

例

curl -X DELETE https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

レスポンス

素の文字列：

"member has been removed"

エラー

• 400 — the owner cannot be removed
• 404 — メンバーが見つからない