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!"
  }'

import requests

url = "{{baseUrl}}/api/invitations/create"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
params = {
    "org_id": "your-org-id"
}
data = {
    "email": "newuser@example.com",
    "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
    "message": "Please join our organization!"
}

response = requests.post(url, headers=headers, params=params, json=data)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/invitations/create";
const headers = {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
};
const params = {
    org_id: "your-org-id"
};
const data = {
    email: "newuser@example.com",
    role_id: "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
    message: "Please join our organization!"
};

axios.post(url, data, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m",
  "email": "newuser@example.com",
  "status": "pending",
  "role": {
    "id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
    "name": "Member"
  },
  "organization": {
    "id": "d07897e2-1ddf-4f11-9434-5fb6f2f5c20d",
    "name": "Acme Inc"
  },
  "token": "inv_Ax92jKsLp8YzR4TbMn5VcWq3",
  "created_at": "2023-08-01T10:00:00Z",
  "expires_at": "2023-08-08T10:00:00Z"
}

Endpoint: POST /api/invitations/create Query Parameters:

Parameter	Required	Description
`org_id`	Yes	Organization ID

Request Body:

Field	Type	Required	Description
`email`	string	Yes	Email address of the person to invite
`role_id`	string	Yes	Role ID to assign to the user upon acceptance
`message`	string	No	Optional personal message to include in the invitation email

Response:

Field	Type	Description
`id`	string (UUID)	Invitation ID
`email`	string	Recipient’s email address
`status`	string	Invitation status (“pending”, “accepted”, “expired”, “revoked”)
`role`	object	Role information
`organization`	object	Organization information
`token`	string	Invitation token (used in acceptance links)
`created_at`	string (datetime)	Creation timestamp
`expires_at`	string (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"

import requests

url = "{{baseUrl}}/api/invitations/list"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
params = {
    "org_id": "your-org-id",
    "status": "pending"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/invitations/list";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};
const params = {
    org_id: "your-org-id",
    status: "pending"
};

axios.get(url, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

[
  {
    "id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m",
    "email": "newuser@example.com",
    "status": "pending",
    "role": {
      "id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
      "name": "Member"
    },
    "invited_by": {
      "id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
      "name": "John Doe"
    },
    "created_at": "2023-08-01T10:00:00Z",
    "expires_at": "2023-08-08T10:00:00Z"
  },
  {
    "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "email": "anotheruser@example.com",
    "status": "pending",
    "role": {
      "id": "9d0e1f2g-3h4i-5j6k-7l8m-9n0o1p2q3r4s",
      "name": "Admin"
    },
    "invited_by": {
      "id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
      "name": "John Doe"
    },
    "created_at": "2023-08-02T09:30:00Z",
    "expires_at": "2023-08-09T09:30:00Z"
  }
]

Endpoint: GET /api/invitations/list Query Parameters:

Parameter	Required	Description
`org_id`	Yes	Organization ID
`status`	No	Filter 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"

import requests

url = "{{baseUrl}}/api/invitations/get"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
params = {
    "invitation_id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/invitations/get";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};
const params = {
    invitation_id: "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m"
};

axios.get(url, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m",
  "email": "newuser@example.com",
  "status": "pending",
  "role": {
    "id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
    "name": "Member"
  },
  "organization": {
    "id": "d07897e2-1ddf-4f11-9434-5fb6f2f5c20d",
    "name": "Acme Inc"
  },
  "invited_by": {
    "id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "name": "John Doe"
  },
  "token": "inv_Ax92jKsLp8YzR4TbMn5VcWq3",
  "message": "Please join our organization!",
  "created_at": "2023-08-01T10:00:00Z",
  "expires_at": "2023-08-08T10:00:00Z"
}

Endpoint: GET /api/invitations/get Query Parameters:

Parameter	Required	Description
`invitation_id`	Yes	Invitation ID

Validate Invitation

Validate an invitation token (used before accepting an invitation).

curl -X GET {{baseUrl}}/api/invitations/validate?token=inv_Ax92jKsLp8YzR4TbMn5VcWq3

import requests

url = "{{baseUrl}}/api/invitations/validate"
params = {
    "token": "inv_Ax92jKsLp8YzR4TbMn5VcWq3"
}

response = requests.get(url, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/invitations/validate";
const params = {
    token: "inv_Ax92jKsLp8YzR4TbMn5VcWq3"
};

axios.get(url, { params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "valid": true,
  "invitation": {
    "id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m",
    "email": "newuser@example.com",
    "organization": {
      "id": "d07897e2-1ddf-4f11-9434-5fb6f2f5c20d",
      "name": "Acme Inc"
    },
    "role": {
      "id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
      "name": "Member"
    },
    "invited_by": {
      "id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
      "name": "John Doe"
    },
    "created_at": "2023-08-01T10:00:00Z",
    "expires_at": "2023-08-08T10:00:00Z"
  }
}

Endpoint: GET /api/invitations/validate Query Parameters:

Parameter	Required	Description
`token`	Yes	Invitation 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"

import requests

url = "{{baseUrl}}/api/invitations/resend"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
params = {
    "invitation_id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m"
}

response = requests.post(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/invitations/resend";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};
const params = {
    invitation_id: "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m"
};

axios.post(url, {}, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "success": true,
  "message": "Invitation resent successfully",
  "invitation": {
    "id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m",
    "email": "newuser@example.com",
    "status": "pending",
    "expires_at": "2023-08-15T10:00:00Z"
  }
}

Endpoint: POST /api/invitations/resend Query Parameters:

Parameter	Required	Description
`invitation_id`	Yes	Invitation 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"

import requests

url = "{{baseUrl}}/api/invitations/revoke"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
params = {
    "invitation_id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m"
}

response = requests.delete(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/invitations/revoke";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};
const params = {
    invitation_id: "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m"
};

axios.delete(url, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "success": true,
  "message": "Invitation revoked successfully"
}

Endpoint: DELETE /api/invitations/revoke Query Parameters:

Parameter	Required	Description
`invitation_id`	Yes	Invitation 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."
  }'

import requests

url = "{{baseUrl}}/api/invitations/bulk_create"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
params = {
    "org_id": "your-org-id"
}
data = {
    "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."
}

response = requests.post(url, headers=headers, params=params, json=data)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/invitations/bulk_create";
const headers = {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
};
const params = {
    org_id: "your-org-id"
};
const data = {
    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."
};

axios.post(url, data, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "success": true,
  "created": 2,
  "failed": 0,
  "invitations": [
    {
      "id": "5a7e8f91-2b3c-4d5e-6f7g-8h9i0j1k2l3m",
      "email": "user1@example.com",
      "status": "pending"
    },
    {
      "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "email": "user2@example.com",
      "status": "pending"
    }
  ]
}

Endpoint: POST /api/invitations/bulk_create Query Parameters:

Parameter	Required	Description
`org_id`	Yes	Organization ID

Request Body:

Field	Type	Required	Description
`invitations`	array	Yes	Array of invitation objects (email, role_id)
`message`	string	No	Optional 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:

User receives an invitation email with a link containing the invitation token
User clicks the link, which takes them to a signup page
User completes the signup form and submits it to the /api/auth/signup_invite endpoint
Upon successful account creation, the user is automatically added to the organization with the designated role

Error Responses

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

🎯 Welcome

🚀 Getting Started

💡 Core Concepts

🏗️ Platform Architecture

🔐 Security & Auth

📡 API Reference

🛠️ Development Guides

🚨 Troubleshooting

Invitations Service API

Authentication

Base URL

Endpoints

Create Invitation

List Invitations

Get Invitation

Validate Invitation

Resend Invitation

Revoke Invitation

Bulk Create Invitations

Accept Invitation (Backend Process)

Error Responses

Implementation Notes

​Authentication

​Base URL

​Endpoints

​Create Invitation

​List Invitations

​Get Invitation

​Validate Invitation

​Resend Invitation

​Revoke Invitation

​Bulk Create Invitations

​Accept Invitation (Backend Process)

​Error Responses

​Implementation Notes

Authentication

Base URL

Endpoints

Create Invitation

List Invitations

Get Invitation

Validate Invitation

Resend Invitation

Revoke Invitation

Bulk Create Invitations

Accept Invitation (Backend Process)

Error Responses

Implementation Notes