The Invitations Service provides endpoints for creating, managing, and responding to organization invitations. It enables organization administrators to invite users to join their organization with specific roles.

​
Authentication

All endpoints require a valid Bearer token in the Authorization header.

​
Base URL

/api/invitations

​
Endpoints

​
Create Invitation

Create a new invitation to join an organization. 
curl -X POST {{baseUrl}}/api/invitations/create?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
    "message": "Please join our organization!"
  }'
Endpoint: POST /api/invitations/create Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
emailstringYesEmail address of the person to invite
role_idstringYesRole ID to assign to the user upon acceptance
messagestringNoOptional personal message to include in the invitation email
Response:
FieldTypeDescription
idstring (UUID)Invitation ID
emailstringRecipient’s email address
statusstringInvitation status (“pending”, “accepted”, “expired”, “revoked”)
roleobjectRole information
organizationobjectOrganization information
tokenstringInvitation token (used in acceptance links)
created_atstring (datetime)Creation timestamp
expires_atstring (datetime)Expiration timestamp

​
List Invitations

Retrieve all invitations for an organization. 
curl -X GET {{baseUrl}}/api/invitations/list?org_id=your-org-id&status=pending \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/invitations/list Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
statusNoFilter by invitation status (pending, accepted, expired, revoked)

​
Get Invitation

Get details about a specific invitation. 
curl -X GET {{baseUrl}}/api/invitations/get?invitation_id=5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/invitations/get Query Parameters:
ParameterRequiredDescription
invitation_idYesInvitation ID

​
Validate Invitation

Validate an invitation token (used before accepting an invitation). 
curl -X GET {{baseUrl}}/api/invitations/validate?token=inv_Ax92jKsLp8YzR4TbMn5VcWq3
Endpoint: GET /api/invitations/validate Query Parameters:
ParameterRequiredDescription
tokenYesInvitation token

​
Resend Invitation

Resend an invitation email. 
curl -X POST {{baseUrl}}/api/invitations/resend?invitation_id=5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: POST /api/invitations/resend Query Parameters:
ParameterRequiredDescription
invitation_idYesInvitation ID

​
Revoke Invitation

Revoke a pending invitation. 
curl -X DELETE {{baseUrl}}/api/invitations/revoke?invitation_id=5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/invitations/revoke Query Parameters:
ParameterRequiredDescription
invitation_idYesInvitation ID

​
Bulk Create Invitations

Create multiple invitations at once. 
curl -X POST {{baseUrl}}/api/invitations/bulk_create?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invitations": [
      {
        "email": "user1@example.com",
        "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l"
      },
      {
        "email": "user2@example.com",
        "role_id": "9d0e1f2g-3h4i-5j6k-7l8m-9n0o1p2q3r4s"
      }
    ],
    "message": "We would like to invite you to join our organization."
  }'
Endpoint: POST /api/invitations/bulk_create Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
invitationsarrayYesArray of invitation objects (email, role_id)
messagestringNoOptional message to include in all invitation emails

​
Accept Invitation (Backend Process)

Note: This endpoint is not directly exposed, as invitation acceptance is handled through the authentication service using a token. The flow for accepting an invitation is:
  1. User receives an invitation email with a link containing the invitation token
  2. User clicks the link, which takes them to a signup page
  3. User completes the signup form and submits it to the /api/auth/signup_invite endpoint
  4. Upon successful account creation, the user is automatically added to the organization with the designated role

​
Error Responses

Status CodeDescription
400Bad Request - Invalid input or validation error
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions (only admins can manage invitations)
404Not Found - Invitation doesn’t exist
409Conflict - User already exists or is already a member of the organization
410Gone - Invitation has expired or been revoked
500Internal Server Error - Server-side error

​
Implementation Notes

  • Invitations expire after 7 days by default
  • When an invitation is resent, its expiration date is extended
  • Users can only be invited to join an organization if they don’t already have an account or are not already members
  • Only users with appropriate permissions (Admins and Owners) can create and manage invitations
  • Invitation tokens are secure, one-time-use tokens that become invalid after acceptance
  • Email notifications are sent automatically when invitations are created or resent