Organization Invitations API

Invite users to join an organization via email. Organization invitations are separate from workspace invitations — accepting an org invitation grants membership to the organization (and cascading access to its workspaces based on role).

List Invitations

Requires admin role in the organization.

GET /api/v1/organizations/{org_id}/invitations
Authorization: Bearer <token>

Response 200 OK

[
  {
    "id": "uuid",
    "organization_id": "uuid",
    "email": "carol@example.com",
    "role": "member",
    "invited_by": "uuid",
    "message": "Welcome to the team!",
    "status": "pending",
    "expires_at": "2026-05-23T00:00:00Z",
    "accepted_at": null,
    "created_at": "2026-05-16T00:00:00Z",
    "last_email_sent_at": "2026-05-16T00:01:00Z",
    "last_email_status": "sent",
    "last_email_error": null,
    "send_attempt_count": 1,
    "invite_url": "https://app.forgexa.net/accept-org-invitation?token=..."
  }
]

Send Invitation

Requires admin role. Sends an invitation email with a unique link. Invitations expire after 7 days.

POST /api/v1/organizations/{org_id}/invitations
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "carol@example.com",
  "role": "member",
  "message": "Welcome to the team!"
}

Response 201 Created

Field	Type	Required	Description
email	string	Yes	Invitee email address
role	string	Yes	admin or member
message	string	No	Personal message included in the email

TIP

If SMTP is configured at the organization level, the invitation email is sent automatically. Otherwise, share the invite_url from the response manually.

Resend Invitation

Resends the invitation email and refreshes the expiration date.

POST /api/v1/organizations/{org_id}/invitations/{invitation_id}/resend
Authorization: Bearer <token>

Response 200 OK — Returns updated invitation with refreshed expires_at.

Revoke Invitation

Cancel a pending invitation. The invitation link becomes invalid.

POST /api/v1/organizations/{org_id}/invitations/{invitation_id}/revoke
Authorization: Bearer <token>

Response 200 OK — Returns invitation with status: "revoked".

Get Invitation Info (Public)

No authentication required. Used by the accept-invitation page to display invitation details before the user logs in or registers.

GET /api/v1/organization-invitations/info?token=<invitation_token>

Response 200 OK

{
  "organization_name": "Acme Corp",
  "email": "carol@example.com",
  "role": "member",
  "inviter_name": "Alice Chen",
  "message": "Welcome to the team!",
  "status": "pending",
  "expires_at": "2026-05-23T00:00:00Z"
}

Accept Invitation

Authenticated user accepts the invitation and joins the organization. The invitation email must match the authenticated user's email.

POST /api/v1/organization-invitations/{token}/accept
Authorization: Bearer <token>

Response 200 OK

{
  "detail": "Invitation accepted. You are now a member of Acme Corp."
}

INFO

If the invitee doesn't have an account, they can register first (the token remains valid for 7 days). Upon registration with the matching email, they are automatically added to the organization.

Invitation Statuses

Status	Description
pending	Sent and awaiting acceptance
accepted	User accepted and joined the organization
expired	Past the 7-day expiration window
revoked	Manually cancelled by an admin