Members API

The Members API uses three distinct scopes so you can mint least-privilege keys for each integration:

• members:read — list, retrieve, search.
• members:write — update fields, change tier, change role (excludes owner transfer).
• members:invite — create new member rows + send invite emails.

Owner transfer is intentionally not API-callable — it must be done from the operator dashboard with two-factor confirmation. This isn't about API surface area; it's about preventing a single compromised key from rotating workspace ownership.

# Inspect your token's scopes
curl https://api.litehq.com/v1/auth/whoami \
  -H 'Authorization: Bearer sk_live_...'

# {
#   "workspace_id": "ws_strand",
#   "scopes": ["members:read", "members:write"],
#   "key_prefix": "sk_live_LX",
#   "created_at": "2026-03-12T08:00:00Z"
# }

Cursor-paginated, like every list endpoint we ship. Default sort is joined_at desc. Useful filters:

• tier — basic | plus | pro | enterprise.
• status — active | trialing | paused | cancelled.
• company_id — for chain operators, scope to a single tenant.
• q — free-text search across name + email.
• include_archived — default false; set true for off-boarding audits.

curl -G https://api.litehq.com/v1/members \
  -H 'Authorization: Bearer sk_live_...' \
  --data-urlencode 'tier=plus' \
  --data-urlencode 'status=active' \
  --data-urlencode 'limit=100'

{
  "id": "mem_J7P3kQ",
  "name": "Anya Rivera",
  "email": "anya@tidelabs.co",
  "tier": "plus",
  "status": "active",
  "role": "member",
  "company": { "id": "co_tide", "name": "Tide Labs" },
  "joined_at": "2025-11-04T09:30:00Z",
  "tokens": { "balance": 124, "monthly_grant": 40 }
}

Two flavours of create exist depending on whether you want the member to receive an invite email or be silently added (e.g. when you've already onboarded them via your own flow):

• Invite flow — send_invite: true (default). Generates a magic-link, emails the member.
• Silent provision — send_invite: false. Creates the row in status=active immediately; you handle the welcome via your own channel.

curl -X POST https://api.litehq.com/v1/members \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "anya@tidelabs.co",
    "name": "Anya Rivera",
    "tier": "plus",
    "company_id": "co_tide",
    "send_invite": true
  }'

const member = await litehq.members.create({
  email: 'anya@tidelabs.co',
  name: 'Anya Rivera',
  tier: 'plus',
  companyId: 'co_tide',
  sendInvite: true,
});

console.log(member.id, member.status);
// mem_J7P3kQ  invited

Two fields drive the bulk of member changes:

• tier — basic, plus, pro, enterprise. Tier upgrades prorate immediately via the workspace's Stripe subscription; downgrades take effect at the next billing cycle.
• role — member, admin, billing_contact. Owner is excluded from API mutation as noted in section 1.

curl -X PATCH https://api.litehq.com/v1/members/mem_J7P3kQ \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "tier": "pro",
    "tier_change_reason": "client_upgrade_request"
  }'

The optional tier_change_reason field is stored in the audit log and surfaces in Settings → Audit logfor compliance. We accept any string ≤ 256 chars; pick a vocabulary that's greppable.

Bulk endpoints let you import, update, or off-board large groups in one round-trip. The request takes an array of operations; the response includes per-op success + error rows so partial failures are recoverable.

curl -X POST https://api.litehq.com/v1/members.bulk \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      { "op": "create", "email": "a@co.com", "tier": "plus" },
      { "op": "create", "email": "b@co.com", "tier": "plus" },
      { "op": "update", "id": "mem_X1", "tier": "pro" },
      { "op": "archive", "id": "mem_X2" }
    ]
  }'

{
  "results": [
    { "op": "create", "status": "ok", "id": "mem_new1" },
    { "op": "create", "status": "ok", "id": "mem_new2" },
    { "op": "update", "status": "ok", "id": "mem_X1" },
    { "op": "archive", "status": "error",
      "error": { "code": "member_not_found", "message": "..." } }
  ],
  "summary": { "ok": 3, "error": 1 }
}

Member webhooks fire on the same endpoint as bookings + billing — the differentiator is event.type. Subscribe by passing event_types when registering the endpoint.

These are the per-role capabilities enforced server-side by RLS and edge-function scope checks. UI affordances mirror them — if the API rejects, the UI will too.