Members API

Manage team seats and roles — the people who share your account's issuers, badges, and credentials.

All endpoints require authentication. See Authentication. Every request is scoped to the authenticated owner's account.

Roles that can be assigned via the API are admin, editor, and viewer. The owner role is reserved for the account holder and cannot be assigned or removed.

List Members

Retrieve all members and pending invitations on your account.

GET /members

Example

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

Response

{
  "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 is active for members who have accepted, or pending for invitations that have not yet been accepted.

---

Invite Member

Invite a person to the account by email. An invitation email with an accept link is sent to the address.

POST /members

Parameters

Parameter	Type	Required	Description
email	string	Yes	Email address to invite (must be a valid email)
role	string	Yes	Role to assign — one of admin, editor, viewer

Example

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"
    }
  }'

Response

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

Errors

• 400 — role must be one of admin, editor, viewer
• 400 — invalid or missing email address
• 400 — seat limit reached — the account has no free seats for the plan (Free: 2, Starter: 5, Pro: 20, including the owner). Remove a member or upgrade the plan.
• 400 — the email is already a member or has a pending invitation on this account

---

Accept Invitation

Accept a pending invitation. The authenticated user's email must match the address the invitation was sent to.

POST /members/accept

Parameters

Parameter	Type	Required	Description
inviteId	string	Yes	The invitation ID from the accept-link email

Example

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"
    }
  }'

Response

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

Errors

• 400 — email does not match invitation — the signed-in email differs from the invited email
• 404 — invitation not found (already accepted, cancelled, or the inviteId is wrong)

---

Update Member Role

Change an existing member's role. Requires owner or admin privileges.

POST /members/{memberId}/role

Parameters

Parameter	Type	Required	Description
memberId	string	Yes	The member ID (path parameter)
role	string	Yes	New role — one of admin, editor, viewer

Example

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"
    }
  }'

Response

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

Errors

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — member not found

---

Remove Member

Remove a member from the account, or cancel a pending invitation. The member immediately loses access and their seat is freed.

DELETE /members/{memberId}

Example

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

Response

A bare string:

"member has been removed"

Errors

• 400 — the owner cannot be removed
• 404 — member not found