Skip to main content
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