Skip to content
SarvexDocs
Esc
↑↓navigate↵open⌘Jpreview

Invite a team member (owner self-serve)

Lets the account owner invite additional teammates directly, without operator involvement. Invited members always join with the staff role — role changes and owner reassignment remain operator-assisted (see /operator/merchants/{merchant_id}/members). Capped at the account’s team-member seat limit (GET /billing → usage.member_cap; defaults to 5, configurable per subscription). Creates the Sarvex-side member record and emails a sign-in link, identical in effect to the operator invite flow.

POST/account/members
Authorization
AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Header parameters
Idempotency-Keystring

Client-generated key; replays return the original result.

Request body
requiredapplication/json
emailstring<email>required
Responses
201

Member invited; sign-in link sent.

user_idstring
emailstring<email>
rolestring
Allowed:ownerstaff
statusstring
Allowed:activeinvited
403

Authenticated but not permitted (e.g. non-operator on an operator route).

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
409

A member with this email already exists, or the account's team-member seat limit has been reached.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST "https://api.sarvex.example.com/v1/account/members" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@example.com"
}'
Response
{
  "user_id": "string",
  "email": "user@example.com",
  "role": "owner",
  "status": "active"
}