Invite a member to a merchant (authorize an email)

Creates the Sarvex-side member record {email, role} and emails a sign-in link. This is the invite — there is no separate IdP step. Sarvex authorizes by email; the IdP (Kinde, including social sign-in) authenticates. On first sign-in the verified token’s email claim is matched to this record, resolving the merchant + role. No password is set or held by Sarvex.

POST/operator/merchants/{merchant_id}/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.

Scopes:operator

Path parameters

merchant_idstringrequired

The merchant being provisioned. Operator-scoped path id (not a tenant selector for merchant-scoped calls).

Header parameters

Idempotency-Keystring

Client-generated key; replays return the original result.

Request body

requiredapplication/json

emailstring<email>required

rolestringrequired

Allowed:ownerstaff

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 for the merchant.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Parameters

merchant_idpath*The merchant being provisioned. Operator-scoped path id (not a tenant selector for merchant-scoped calls).Idempotency-KeyheaderClient-generated key; replays return the original result.

Bodyapplication/json

emailstring*rolestring*

Request

curl -X POST "https://api.sarvex.example.com/v1/operator/merchants/string/members" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@example.com",
  "role": "owner"
}'

const response = await fetch("https://api.sarvex.example.com/v1/operator/merchants/string/members", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"email\": \"user@example.com\",\n  \"role\": \"owner\"\n}"
});

import requests

response = requests.post(
    "https://api.sarvex.example.com/v1/operator/merchants/string/members",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"email\": \"user@example.com\",\n  \"role\": \"owner\"\n}",
)

Response

{
  "user_id": "string",
  "email": "user@example.com",
  "role": "owner",
  "status": "active"
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}