Issue Invite
Create and send an invitation to a new administrator.
Endpoint
/auth/admin/users/invitationsIssue an invitation to a new admin user. The invitation token is returned once and must be delivered securely to the invitee.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Content-Type | string | Yes | application/json |
Request Body- Invitation details
{
"email": "admin@example.com",
"full_name": "John Doe",
"role": "operator",
"expires_in_minutes": 1440
}Response- Invitation created successfully
{
"invite": {
"invite_id": "550e8400-e29b-41d4-a716-446655440000",
"email": "admin@example.com",
"full_name": "John Doe",
"role": "operator",
"status": "pending",
"expires_at": "2025-01-15T10:30:00Z",
"invited_by": "660e8400-e29b-41d4-a716-446655440001",
"created_at": "2025-01-14T10:30:00Z"
},
"token": "secure_invitation_token_here"
}Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | validation_failed | Invalid email format or role |
| 403 | forbidden | Admin role required |
| 429 | rate_limit_exceeded | Rate limit: 5/min, 50/day |
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Email address of the invitee | |
| full_name | string | No | Full name of the invitee |
| role | string | Yes | Role: admin, operator, viewer, or finance |
| expires_in_minutes | integer | No | Invitation expiry time in minutes |
List Invitations
Retrieve a paginated list of admin invitations.
Endpoint
/auth/admin/users/invitationsList all admin invitations with optional filtering.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status (comma-separated)Values: pending, accepted, cancelled, expired |
email | string | No | Filter by email (partial match) |
role | string | No | Filter by roleValues: admin, operator, viewer, finance |
limit | integer | No (default: 20) | Page size |
offset | integer | No (default: 0) | Page offset |
Response- List of invitations
{
"invitations": [
{
"invite_id": "550e8400-e29b-41d4-a716-446655440000",
"email": "admin@example.com",
"full_name": "John Doe",
"role": "operator",
"status": "pending",
"expires_at": "2025-01-15T10:30:00Z",
"created_at": "2025-01-14T10:30:00Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}Error Responses
| Status | Code | Description |
|---|---|---|
| 403 | forbidden | Admin role required |
Resend Invitation
Resend an existing invitation with a new token.
Endpoint
/auth/admin/users/invitations/{inviteID}/resendResend an invitation. Generates a new token and optionally updates the expiration.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
inviteID | string | Yes | UUID of the invitation |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
expires_in_minutes | integer | No | New expiration time in minutes |
Response- Invitation resent
{
"invite": {
"invite_id": "550e8400-e29b-41d4-a716-446655440000",
"email": "admin@example.com",
"status": "pending",
"expires_at": "2025-01-16T10:30:00Z"
},
"token": "new_secure_invitation_token"
}Error Responses
| Status | Code | Description |
|---|---|---|
| 404 | not_found | Invitation not found |
| 429 | rate_limit_exceeded | Rate limit: 5/min, 50/day |
Cancel Invitation
Cancel a pending invitation.
Endpoint
/auth/admin/users/invitations/{inviteID}/cancelCancel an invitation. The invitation token will no longer be valid.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
inviteID | string | Yes | UUID of the invitation to cancel |
Response- No content on success
Error Responses
| Status | Code | Description |
|---|---|---|
| 404 | not_found | Invitation not found |
| 400 | invalid_status | Invitation already accepted or cancelled |
Accept Invitation
Accept an invitation and create an admin account.
Endpoint
/auth/admin/invitations/acceptAccept an invitation using the secure token. This endpoint is unauthenticated - the token provides authorization.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Content-Type | string | Yes | application/json |
Request Body- Invitation acceptance details
{
"token": "secure_invitation_token",
"password": "SecurePassword123!",
"full_name": "John Doe"
}Response- Account created successfully
{
"user_id": "770e8400-e29b-41d4-a716-446655440002",
"email": "admin@example.com",
"role": "operator"
}Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | validation_failed | Password must be at least 8 characters |
| 401 | invite_invalid | Invitation token invalid or expired |
| 429 | rate_limit_exceeded | Rate limit: 5/min, 30/day |
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| token | string | Yes | Secure invitation token from email |
| password | string | Yes | Password (min 8 characters) |
| full_name | string | No | Override the invited name |