vsmsconnect — API — invites

← all endpoints

POST/api/v1/invites auth: jwt (administrator)

Create a one-time invite. Generates a UUID token, stores `invite:{uuid}` in Redis with TTL INVITE_TTL_SECONDS (default 72h) holding { email, roles, organizationId=businessId, invitedBy=actorUserId }, and sends an invite email. On email failure the Redis token is deleted to avoid orphans.

handlers: InvitesController.create

Inputs

namerequireddefaultdescription
email body
string (email)		yes—Invitee email address.
roles body
UserRole[]		yes—Roles to assign on registration (min 1).

Outputs

201
APIResponseDataObject<InviteDTO>
{ inviteToken, email, roles, organizationId, inviteUrl } — inviteUrl is APP_URL/register-invited?token=<uuid>.
401
APIError
AUTH_UNAUTHORIZED — missing/invalid bearer token.
403
APIError
USER_FORBIDDEN — caller is not Administrator.
422
APIError
VALIDATION_ERROR — schema violation.
502
APIError
Bubbled email-service failure (token already cleaned up).
GET/api/v1/invites/:token auth: none

Validate an invite token and return its metadata so the registration page can pre-fill the email and show the role(s). Public — invite recipients have no account yet.

handlers: InvitesController.validate

Inputs

namerequireddefaultdescription
token path
uuid		yes—Invite token from the email link.

Outputs

200
APIResponseDataObject<InviteDTO>
{ inviteToken, email, roles, organizationId }.
404
APIError
INVITE_INVALID — token missing from Redis (expired or never existed).