Invites
Mint, assign, send and claim invites, and read your own mint authority before showing a form.
An invite moves DRAFT to SENT to one of CLAIMED, REVOKED or EXPIRED. Three parties can
be attached and none implies another: the creator is accountable for it existing, the holder
may send it, and the recipient may claim it. Surfaces that say who an invite is "from" name the
holder when there is one and the creator otherwise - the person who handed it over, not the account
that minted it.
Three endpoints face a stranger or a newcomer and are hardened accordingly. preview returns a
generic { valid: false } on every failure path so a caller cannot tell a wrong code from an
expired one, answers in constant time, and is limited to 10 a minute per IP. precheck shares that
per-IP limit. claim is limited to 5 a minute per user and is final - there is no unclaim. All
three fail closed when the limiter is unreachable.
There is no invite email or message: an invite is a claim link, and whoever sends it delivers it.
A signup that arrives with a code claims it in the same transaction that creates the account - see
Users for X-Invite-Code.
Read mint-authority before rendering a mint form. It tells you the caller's daily quota and
whether they may attach a role, so you can hide a form that would only 403 on submit.
Managing invites
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /api/invites | user | List the invites you minted, newest first. scope=held lists the ones assigned to you to send, status filters (repeatable) and limit is 1-500, default 100. An admin sees every invite, and may narrow with creatorId. The answer carries items and a per-status summary. |
POST | /api/invites | user | Mint a draft invite (201). Every field is optional: claimBinding (BEARER, EMAIL, X_HANDLE, STX_ADDRESS or USER) with its bindingValue, recipientUserId, holderUserId (mint and assign in one call), roleId, appId, grantAppIds, fundingStxMicro, message and expiresAt. Minting follows the creator's role tier - see RBAC. |
DELETE | /api/invites/{id} | user | Delete a draft. |
GET | /api/invites/{id} | user | One invite. |
PATCH | /api/invites/{id} | user | Update a draft. |
POST | /api/invites/{id}/assign | user | Assign a draft to a holder with { holderUserId }, who may then send it. |
POST | /api/invites/{id}/send | user | Send an invite, optionally binding it to its recipient with { binding: { kind: "EMAIL" or "X_HANDLE", value } }. A sender cannot bind an invite to their own verified email or handle. |
POST | /api/invites/{id}/send-to-waitlist | user | Spend an unaddressed DRAFT on someone from the waitlist pool: { signupId }, and the server binds it to the contact it holds. TAKEN (409) means somebody else got there first and the invite is untouched. |
POST | /api/invites/{id}/revoke | user | Revoke an invite. |
GET | /api/invites/mint-authority | user | Your own mint quota and whether you may attach a role. Read this before rendering a mint form. |
An invite sent to someone on the waitlist reads with bindingValue: null to everyone but an admin, on every invite read, because the member who spent it is never told how to reach that person; claimBinding still says which kind of account it waits for.
Claiming
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /api/invites/preview | app key | Check a code without claiming it ({ code }). Returns a generic { valid: false } on every failure path. |
POST | /api/invites/precheck | app key + user | Check whether the signed-in person could claim a code ({ code }), including an email or X binding. Accepts a verified hosted-account token whose wallet is not listed yet, so it works right after wallet creation. A system error answers 500 so a client falls through to the claim rather than blocking a real signup. |
POST | /api/invites/claim | user | Claim a code ({ code }) for the authenticated user. Claiming is final - there is no unclaim. |