Organizations API

Manage the current user's organization, its members, and invitations. Organization routes are mounted under /v1/organization and are scoped to the organization of the authenticated user (there is no {org_id} path parameter). Invitation routes addressed to the current user live under /v1/invitations. All routes require an authenticated session.

Roles

Membership roles, from least to most privileged: viewer → member → admin → super_admin. Invitations may assign admin, member, or viewer.

Get Organization

GET /v1/organization

Returns the current user's organization and the user's role within it.

Response:

{
  "id": 1,
  "name": "Acme Corp",
  "slug": "acme-corp",
  "description": "Acme's organization",
  "status": "active",
  "role": "admin",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T09:00:00Z"
}

Update Organization

PATCH /v1/organization

Request body:

{
  "name": "Acme Corp",
  "description": "Updated description"
}

Field	Type	Required	Notes
`name`	string	No	Max 255 chars; cannot be blank if provided
`description`	string	No	Send `null` to clear

Returns the updated organization (same schema as above).

List Members

GET /v1/organization/members

Response — a JSON array of members:

[
  {
    "id": 10,
    "user_id": 42,
    "email": "alice@example.com",
    "name": "Alice",
    "role": "admin",
    "joined_at": "2025-01-15T09:00:00Z"
  }
]

Send Invitation

POST /v1/organization/invitations

Request body:

{
  "email": "colleague@example.com",
  "role": "member"
}

Field	Type	Required	Notes
`email`	string	Yes	3–320 chars
`role`	string	No	`admin`, `member`, or `viewer` (default `member`)

Response:

{
  "id": 5,
  "organization_id": 1,
  "organization_name": "Acme Corp",
  "invitee_email": "colleague@example.com",
  "invitee_user_id": null,
  "invited_by_user_id": 42,
  "role": "member",
  "status": "pending",
  "email_status": "sent",
  "email_sent_at": "2025-06-17T10:00:00Z",
  "email_last_error": null,
  "created_at": "2025-06-17T10:00:00Z",
  "expires_at": "2025-06-24T10:00:00Z",
  "responded_at": null
}

Resend Invitation

POST /v1/organization/invitations/{invitation_id}/resend

Re-sends the invitation email and returns the updated invitation object.

List Organization Invitations

GET /v1/organization/invitations

Returns a JSON array of invitations for the current organization.

My Invitations

Invitations addressed to the signed-in user, plus token-based preview and response flows.

GET /v1/invitations
GET /v1/invitations/by-token/{token}
POST /v1/invitations/by-token/{token}/accept
POST /v1/invitations/by-token/{token}/reject
POST /v1/invitations/{invitation_id}/reject

GET /v1/invitations — list the current user's invitations.
GET /v1/invitations/by-token/{token} — preview an invitation by its token (no sign-in required); returns organization name, invitee email, role, status, and expiry.
POST /v1/invitations/by-token/{token}/accept — accept an invitation using its token.
POST /v1/invitations/by-token/{token}/reject / POST /v1/invitations/{invitation_id}/reject — decline an invitation by token or by id.

Flows for accepting an invitation as a brand-new user:

POST /v1/invitations/register
POST /v1/invitations/sso/google/start

POST /v1/invitations/register — create an account from an invitation token (fields: token, password, optional first_name, last_name, country, contact_number). Returns an authenticated session.
POST /v1/invitations/sso/google/start — begin Google SSO sign-up for an invitation (field: token); returns an authorization_url to redirect the user to.