Invites

Invites bring new people into a workspace. An admin creates one against an email address or phone number; the recipient gets a one-time link and either accepts with an existing account or signs up in the same step.

The workspace-scoped routes take a session JWT or API key; the top-level accept routes are designed for the recipient, who may not be signed in yet.

Workspace-side (admin)

Endpoint	Description
POST /v1/workspaces/{wid}/invites	Create an invite (admin) → 201 {invite, link}
GET /v1/workspaces/{wid}/invites	List pending invites (any member; token hashes stripped)
POST /v1/workspaces/{wid}/invites/{id}/revoke	Revoke a pending invite (admin)

Create an invite

curl -X POST https://api.knobs.io/v1/workspaces/{wid}/invites \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "email": "sam@example.com",
    "role": "member",
    "firstName": "Sam",
    "lastName": "Ito"
  }'

{
  "invite": { "id": "inv_51d0…", "channel": "email", "email": "sam@example.com", "role": "member", "status": "pending" },
  "link": "https://app.knobs.io/invite/inv_51d0…?token=…"
}

• channel is email or sms (with phone instead of email).
• firstName/lastName are optional; when set, the invitee’s name is locked to them.
• The link is also delivered out-of-band (email/SMS). Duplicate pending invites to the same contact return 409; invite creation is rate-limited (429).

Recipient-side

These routes live at the top level — the recipient doesn’t need to know the workspace id, and authorization is the invite token itself.

Endpoint	Auth	Description
GET /v1/invites/{id}	public + token	Safe invite preview for the landing page. Pass the token in the X-Invite-Token header (preferred — keeps it out of URLs and logs) or ?token= as a fallback
POST /v1/invites/{id}/accept	authed	{token} — accept as the signed-in caller; creates the membership
POST /v1/invites/{id}/accept-signup	anonymous	Invite-is-the-signup: {token, firstName?, lastName?, localPart?, password} → {email, uid} — creates the account, canonical address, membership, and mailbox in one step

Preview an invite

curl -H "X-Invite-Token: <token>" https://api.knobs.io/v1/invites/{id}

{
  "invite": {
    "workspaceName": "Acme",
    "role": "member",
    "firstName": "Sam",
    "lastName": "Ito",
    "namesLocked": true,
    "addressFormat": "first"
  }
}

Accept (existing account)

curl -X POST https://api.knobs.io/v1/invites/{id}/accept \
  -H "Authorization: Bearer <session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"token": "<invite-token>"}'

Returns the new membership. Accepting also imports the invite contact as a verified recovery contact, so an invited user is onboarding-complete immediately.

Common errors

Code	Meaning
401 invalid_token	wrong or missing invite token
410 gone	the invite expired
409 conflict	no longer pending (already accepted or revoked)