[FEAT]: Send Organisation Invite Via Email

Description

Create a system for inviting users to organisations via email with time-limited invitation links, supporting multiple invitations at once.

Authentication and Authorization

API endpoint require a valid JWT token in the Authorization header
Only users with the "Admin" role for the specific organization can send invitations

Acceptance Criteria

Admins can send invitations to single or multiple email addresses
Admins can specify which organisation a user can be invited to
System supports sending up to 50 invitations in a single request

Data Validation and Sanitization:

The API should validate the request payload to ensure the email field is present and valid
The API should validate that the org_id is a valid UUID
The JWT in the Authorization header must be valid and not expired
The API should validate that the requesting user has admin rights for the specified organization

Purpose

To invite users to join an organisation by sending secure, time-limited invite links via emails

Expected Outcome

A fully functional invitation system that allows organisation admins to invite new members and users (single or multiple) to join organisations through secure, time-limited invitation links sent to their email addresses.

API Endpoints

1. Send Invitation(s) [POST] /api/v1/organisations/send-invite

Request Headers: Authorization: Bearer

Request Body:

{
  "emails": ["user1@example.com", "user2@example.com", "user3@example.com"],
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Success Response (201 Created):

Content-Type: application/json

{
"message": "Invitation(s) sent successfully",
"invitations": [
{
"email": "user1@example.com",
"organization": "My Organization",
"expires_at": "2023-07-23T00:00:00Z"
},
{
"email": "user2@example.com",
"organization": "My Organization",
"expires_at": "2023-07-23T00:00:00Z"
},
{
"email": "user3@example.com",
"organization": "My Organization",
"expires_at": "2023-07-23T00:00:00Z"
}
]
}

Failure Response (400 Bad Request): Content-Type: application/json

{
"error": "Invalid request",
"message": "One or more email addresses are not valid"
}

Failure Response (403 Forbidden): Content-Type: application/json

{
"error": "Unauthorized",
"message": "You do not have admin rights for this organization"
}

Error Handling

Invalid email format: Return 400 Bad Request with appropriate error message
Invalid org_id (not a UUID): Return 400 Bad Request with appropriate error message
Organization not found: Return 404 Not Found with appropriate error message
Unauthorized access: Return 403 Forbidden with appropriate error message
Exceed emails limit: Return 413 Payload Too Large
Rate limit exceeded: Return 429 Too Many Requests
Invalid or expired JWT: Return 401 Unauthorized with appropriate error message
Server errors: Return 500 Internal Server Error with a generic error message

Requirements

[ ] Create API for sending invitations to multiple email addresses
[ ] Implement JWT authentication protection for API endpoint
[ ] Implement authorization checks for admin actions
[ ] Implement email sending for invitations
[ ] Implement rate limiting for invitation sending to prevent abuse
[ ] Write tests for the invitation system

Testing

Unit tests for invitation sending
Integration tests for the end-to-end invitation flow
Test cases for all error scenarios
Test cases for authorization and authentication

hngprojects / hng_boilerplate_python_fastapi_web

[FEAT]: Send Organisation Invite Via Email #84