Invitations Service API

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:

Request Body:

Response:

​

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:

​

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:

​

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:

​

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:

​

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:

​

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:

Request Body:

​

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

​

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