Organizations API

Overview

The Organizations API provides endpoints for managing organizations, their members, invitations, and rich organization profiles. All endpoints require admin authentication.

Organizations

List Organizations

From /src/pages/api/admin/organizations.ts:59-106:

curl "https://your-domain.com/api/admin/organizations?includeMembers=true" \
  -H "Authorization: Bearer <token>"

Query Parameters

organizationId

string

Fetch single organization by ID (includes members)

includeMembers

boolean

default:"false"

Include member list for each organization

Create Organization

From /src/pages/api/admin/organizations.ts:125-133:

curl -X POST "https://your-domain.com/api/admin/organizations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "name": "My Organization",
    "slug": "my-org"
  }'

Request Body

action

string

required

Must be "create"

name

string

required

Organization name

slug

string

required

URL-friendly organization slug (unique)

Set Active Organization

From /src/pages/api/admin/organizations.ts:168-171:

{
  "action": "set-active",
  "organizationId": "org_789"
}

Sets the user’s active organization context (stored in session).

Organization Members

List Members & Invitations

From /src/pages/api/admin/organizations/members.ts:20-46:

GET /api/admin/organizations/members?organizationId=org_123

Response

{
  "members": [
    {
      "id": "mem_001",
      "userId": "usr_456",
      "role": "owner",
      "createdAt": "2024-01-15T10:00:00Z",
      "name": "John Doe",
      "email": "john@example.com",
      "image": "https://example.com/avatar.jpg"
    },
    {
      "id": "mem_002",
      "userId": "usr_789",
      "role": "admin",
      "createdAt": "2024-02-01T14:00:00Z",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "image": null
    }
  ],
  "invitations": [
    {
      "id": "inv_001",
      "organizationId": "org_123",
      "email": "newmember@example.com",
      "role": "member",
      "status": "pending",
      "expiresAt": "2024-03-17T10:00:00Z"
    }
  ]
}

Invite Member

From /src/pages/api/admin/organizations/members.ts:64-75:

curl -X POST "https://your-domain.com/api/admin/organizations/members" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @invite.json

Invitation Email

From /src/lib/auth/auth.ts:162-172, invited users receive an email:

Subject: Invitation à rejoindre {organizationName}
Body: Cliquez ici pour rejoindre : {url}/invite/{invitationId}

Request Body

action

string

required

Must be "invite"

organizationId

string

required

Organization ID

string

required

Email address to invite

role

string

default:"member"

Member role: owner, admin, member

Update Member Role

From /src/pages/api/admin/organizations/members.ts:77-88:

{
  "action": "update-role",
  "organizationId": "org_123",
  "memberId": "mem_002",
  "role": "admin"
}

Remove Member

From /src/pages/api/admin/organizations/members.ts:90-100:

{
  "action": "remove-member",
  "organizationId": "org_123",
  "memberId": "mem_002"
}

Cancel Invitation

From /src/pages/api/admin/organizations/members.ts:102-109:

{
  "action": "cancel-invitation",
  "organizationId": "org_123",
  "invitationId": "inv_001"
}

Add Existing User as Member

From /src/pages/api/admin/organizations.ts:140-152:

{
  "action": "add-member",
  "organizationId": "org_123",
  "userId": "usr_999",
  "role": "member"
}

Directly adds an existing user without sending an invitation.

Organization Profiles

List Organization Profiles

From /src/pages/api/admin/organizations/profile.ts:21-38:

GET /api/admin/organizations/profile

Response

{
  "organizations": [
    {
      "id": "org_123",
      "name": { "fr": "Acme Corp", "en": "Acme Corp" },
      "slug": "acme-corp",
      "description": { "fr": "Une entreprise innovante" },
      "url": "https://acme.com",
      "logo": "https://acme.com/logo.png",
      "email": "contact@acme.com",
      "telephone": "+33123456789",
      "address": {
        "streetAddress": "123 rue Example",
        "addressLocality": "Paris",
        "postalCode": "75001",
        "addressCountry": "FR"
      },
      "legalName": { "fr": "Acme Corporation SARL" },
      "taxID": "FR12345678901",
      "foundingDate": "2010-05-15",
      "numberOfEmployees": 50,
      "isActive": true,
      "isFeatured": false
    }
  ]
}

Get Single Organization Profile

GET /api/admin/organizations/profile?id=org_123

Returns full profile details for one organization.

Create Organization Profile

From /src/pages/api/admin/organizations/profile.ts:57-89:

curl -X POST "https://your-domain.com/api/admin/organizations/profile" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @org-profile.json

Request Body

action

string

required

Must be "create"

name

object

required

Multilingual name object (e.g., { "fr": "...", "en": "..." })

slug

string

required

URL-friendly slug

description

object

Multilingual description

url

string

Organization website URL

logo

string

Logo image URL

image

string

Cover image URL

string

Contact email

telephone

string

Contact phone number

address

object

Address object with streetAddress, addressLocality, postalCode, addressCountry

legalName

object

Legal name (multilingual)

taxID

string

Tax identification number

foundingDate

string

ISO 8601 date (YYYY-MM-DD)

numberOfEmployees

number

Employee count

isActive

boolean

default:"true"

Organization is active

isFeatured

boolean

default:"false"

Mark as featured

Update Organization Profile

From /src/pages/api/admin/organizations/profile.ts:91-130:

{
  "action": "update",
  "organizationId": "org_123",
  "name": { "fr": "Nouveau Nom" },
  "description": { "fr": "Nouvelle description" },
  "numberOfEmployees": 60,
  "isActive": true
}

Only provided fields are updated. Supports all fields from the create schema.

Toggle Organization Status

From /src/pages/api/admin/organizations/profile.ts:132-146:

{
  "action": "toggle-active",
  "organizationId": "org_123",
  "isActive": false
}

Delete Organization Profile

From /src/pages/api/admin/organizations/profile.ts:148-153:

{
  "action": "delete",
  "organizationId": "org_123"
}

Deletes the rich organization profile (does not delete the core organization or members).

Organization Roles

Available Roles

From Better Auth organization plugin:

owner - Full control, can delete organization
admin - Manage members, settings, content
member - Basic access

Role Permissions

Configured in /src/lib/auth/permissions.ts using accesscontrol:

roles.owner.inherit('admin');
roles.admin.inherit('member');
roles.member.read('profile');

Common Response Codes

Code	Description
200	Success
201	Created
400	Invalid request (missing fields)
403	Not admin (forbidden)
404	Organization not found
500	Server error

Error Responses

Common Errors

Error	Description
`forbidden`	User is not admin
`missing_action`	Action field is required
`missing_organizationId`	Organization ID is required
`missing_name_or_slug`	Name and slug required for creation
`missing_userId_or_role`	User ID and role required
`missing_email`	Email required for invitation
`not_found`	Organization or member not found
`unknown_action`	Invalid action specified

API Overview

Authentication and security

Better Auth Orgs

Better Auth organization plugin docs

Architecture

Database

API

Overview

Organizations

List Organizations

Query Parameters

Create Organization

Request Body

Set Active Organization

Organization Members

List Members & Invitations

Response

Invite Member

Invitation Email

Request Body

Update Member Role

Remove Member

Cancel Invitation

Add Existing User as Member

Organization Profiles

List Organization Profiles

Response

Get Single Organization Profile

Create Organization Profile

Request Body

Update Organization Profile

Toggle Organization Status

Delete Organization Profile

Organization Roles

Available Roles

Role Permissions

Common Response Codes

Error Responses

Common Errors

API Overview

Better Auth Orgs

Build docs developers (and LLMs) love

Architecture

Database

API

Documentation Index

​Overview

​Organizations

​List Organizations

​Query Parameters

​Create Organization

​Request Body

​Set Active Organization

​Organization Members

​List Members & Invitations

​Response

​Invite Member

​Invitation Email

​Request Body

​Update Member Role

​Remove Member

​Cancel Invitation

​Add Existing User as Member

​Organization Profiles

​List Organization Profiles

​Response

​Get Single Organization Profile

​Create Organization Profile

​Request Body

​Update Organization Profile

​Toggle Organization Status

​Delete Organization Profile

​Organization Roles

​Available Roles

​Role Permissions

​Common Response Codes

​Error Responses

​Common Errors

​Related Resources

API Overview

Better Auth Orgs

Build docs developers (and LLMs) love

Overview

Organizations

List Organizations

Query Parameters

Create Organization

Request Body

Set Active Organization

Organization Members

List Members & Invitations

Response

Invite Member

Invitation Email

Request Body

Update Member Role

Remove Member

Cancel Invitation

Add Existing User as Member

Organization Profiles

List Organization Profiles

Response

Get Single Organization Profile

Create Organization Profile

Request Body

Update Organization Profile

Toggle Organization Status

Delete Organization Profile

Organization Roles

Available Roles

Role Permissions

Common Response Codes

Error Responses

Common Errors

Related Resources