Invites API

Invites allow admins to invite new users to an organization. When the server registration mode is set to invite, users must redeem an invite token during registration.

Create Invite

Admin creates an invite token for a new member.

POST /invites

Requires: JWT access token with admin or owner role.

Request

{
  "email": "bob@example.com",
  "role": "member",
  "expiresIn": "72h"
}

Response — 201 Created

{
  "inviteId": "invite-uuid",
  "token": "raw-invite-token"
}

Errors

• 400 INVALID -- Validation failed
• 403 FORBIDDEN -- Not authorized to create invites

Example

curl -X POST https://vault.example.com/api/v1/invites \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bob@example.com",
    "role": "member",
    "expiresIn": "72h"
  }'

List Invites

List all pending invites for an organization.

GET /invites?orgId=<org-uuid>

Requires: JWT access token with admin or owner role.

Query Parameters

Response — 200 OK

[
  {
    "id": "invite-uuid",
    "email": "bob@example.com",
    "role": "member",
    "inviterId": "550e8400-...",
    "expiresAt": "2026-04-12T12:00:00Z",
    "createdAt": "2026-04-09T12:00:00Z"
  }
]

Errors

• 403 FORBIDDEN -- Not authorized to list invites

Example

curl -H "Authorization: Bearer <access_token>" \
     "https://vault.example.com/api/v1/invites?orgId=org-uuid"

Revoke Invite

Admin revokes a pending invite.

DELETE /invites/:inviteId

Requires: JWT access token with admin or owner role.

Response — 204 No Content

No response body.

Errors

• 403 FORBIDDEN -- Not authorized to revoke invites
• 404 NOT_FOUND -- Invite not found

Example

curl -X DELETE -H "Authorization: Bearer <access_token>" \
     https://vault.example.com/api/v1/invites/invite-uuid

Redeem Invite

New user redeems an invite token during registration. This validates the token and returns the organization and role details. The returned information is then used during the /auth/register call (pass the token as inviteToken).

POST /invites/redeem

This endpoint is public (no JWT required).

Request

{
  "token": "raw-invite-token"
}

Response — 200 OK

{
  "orgId": "org-uuid",
  "email": "bob@example.com",
  "role": "member"
}

Errors

• 400 INVITE_NOT_REDEEMABLE -- Token is expired, already used, or revoked
• 404 NOT_FOUND -- Invite token not found

Example

curl -X POST https://vault.example.com/api/v1/invites/redeem \
  -H "Content-Type: application/json" \
  -d '{"token": "raw-invite-token"}'