Team & Roles

Returns every team member with status in active or pending. Revoked members are excluded. Sorted by role, then creation time. Authenticated with a JWT Bearer token and team:read permission.

When a member is assigned to a custom role, role is null and custom_role is populated. When assigned to a built-in role, the reverse: role carries the enum, custom_role is null.

Creates a pending team member with first_name and last_name already set, then emails an activation link (72h TTL) where the user picks a password. Authenticated with a JWT Bearer token and team:write permission.

Use this when the owner wants to set everything up front. The slimmer /v1/merchant/team/invite is the right choice when only the email is known.

Exactly one of role or custom_role_id must be supplied. role may not be owner — use /v1/merchant/team/transfer-ownership instead. You can only assign permissions you yourself hold.

Creates a pending team member with blank first_name / last_name and emails an activation link (72h TTL). Authenticated with a JWT Bearer token and team:write permission.

The invitee fills in their name + password on the accept page. Exactly one of role or custom_role_id must be supplied — role may not be owner. You can only assign permissions you yourself hold.

Used by the accept page. Validates the invite token and returns the email, business name, and any pre-populated name fields so the form can render correctly (or skip name entry entirely if both names are already set).

No authentication required — the token in the query string is the authentication. Returns 401 if the token is invalid, expired, or the invite has already been used / revoked.

Consumes the invite token from the activation email, sets the password, flips status to active, and stamps email_verified=true. No prior authentication required — the token in the body is the authentication.

first_name and last_name are optional when the owner pre-populated them via POST /v1/merchant/team (direct create). If the invitee provides them, the supplied values overwrite the pre-populated ones.

Updates the target member's role and force-logs them out by bumping their token version. Authenticated with a JWT Bearer token and team:write permission.

Exactly one of role or custom_role_id must be supplied. You cannot change your own role, cannot demote the owner (use transfer-ownership first), and cannot grant a permission set you do not yourself hold.

Generates a new invite token (72h TTL), emails it, and bumps the invited_at timestamp on the user row. Authenticated with a JWT Bearer token and team:write permission.

Only works on members with status=pending. Active or revoked members get a 400.

Removes a team member. Authenticated with a JWT Bearer token and team:write permission.

Behavior depends on the target's status:

- `pending`: hard-deleted. The email is freed for re-invite. - `active`: soft-deleted — status flips to revoked, token version is bumped (force-logout), the row stays for audit-trail continuity.

You cannot remove yourself, and you cannot remove the owner (transfer ownership first).

Moves the owner role to another active team member. The previous owner is demoted to admin. Owner only — non-owners get 403. Authenticated with a JWT Bearer token and merchant_profile:write permission.

Requires re-authentication: current password plus a current totp_code. The owner must already have 2FA enabled (else 403). Both old and new owner are emailed a confirmation.

The target user must be on the same merchant and have status=active. Both users' token versions are bumped, forcing a fresh sign-in.

Lists every custom role on the merchant, oldest first. Each entry includes a member_count so the dashboard can flag in-use roles. Authenticated with a JWT Bearer token and team:read permission.

A merchant may have up to 25 custom roles. Built-in roles (owner, admin, developer, finance, support) are not returned here — they're implicit on every account.

Creates a new custom role. Authenticated with a JWT Bearer token and team:write permission.

Permission keys must be drawn from the platform [permission catalog](#permission-catalog) — unknown keys return 400. You cannot create a role whose permissions exceed your own (e.g. an admin cannot create a role granting api_keys:write because admins don't hold that key). Names are unique per merchant (case-insensitive); the five built-in role names (owner, admin, developer, finance, support) are reserved. The merchant cap is 25 custom roles.

Returns one custom role with its permission list and up to 50 active/pending assignees. Authenticated with a JWT Bearer token and team:read permission.

Updates a custom role. Authenticated with a JWT Bearer token and team:write permission.

All fields are optional — supply just the ones you want to change. When permissions changes, every assignee's token version is bumped so they re-authenticate against the new set on their next request. You must hold every permission in both the existing role and the new role; you cannot touch a role that already grants something you lack.

Deletes a custom role. Authenticated with a JWT Bearer token and team:write permission.

Blocked when any team member is still assigned — reassign them via PATCH /v1/merchant/team/:user_id/role first. You must hold every permission the role grants.