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>"

{
  "organizations": [
    {
      "id": "org_123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "createdAt": "2024-01-15T10:00:00Z",
      "logo": "https://example.com/logo.png",
      "members": [
        {
          "id": "mem_001",
          "userId": "usr_456",
          "role": "owner",
          "createdAt": "2024-01-15T10:00:00Z"
        }
      ]
    }
  ]
}

Query Parameters

string

Fetch single organization by ID (includes members)

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"
  }'

{
  "organization": {
    "id": "org_789",
    "name": "My Organization",
    "slug": "my-org",
    "createdAt": "2024-03-03T15:00:00Z"
  }
}

Request Body

string

required

Must be "create"

string

required

Organization name

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

{
  "action": "invite",
  "organizationId": "org_123",
  "email": "newmember@example.com",
  "role": "member"
}

{
  "invitation": {
    "id": "inv_002",
    "organizationId": "org_123",
    "email": "newmember@example.com",
    "role": "member",
    "status": "pending",
    "expiresAt": "2024-03-17T10:00:00Z"
  }
}

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

string

required

Must be "invite"

string

required

Organization ID

string

required

Email address to invite

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

{
  "action": "create",
  "name": { "fr": "Mon Organisation", "en": "My Organization" },
  "slug": "my-org",
  "description": { "fr": "Description en français" },
  "url": "https://myorg.com",
  "logo": "https://myorg.com/logo.png",
  "email": "contact@myorg.com",
  "telephone": "+33123456789",
  "address": {
    "streetAddress": "10 rue Example",
    "addressLocality": "Lyon",
    "postalCode": "69001",
    "addressCountry": "FR"
  },
  "legalName": { "fr": "Mon Organisation SAS" },
  "taxID": "FR98765432109",
  "foundingDate": "2020-01-01",
  "numberOfEmployees": 15,
  "isActive": true,
  "isFeatured": false
}

{
  "organization": {
    "id": "org_999",
    "name": { "fr": "Mon Organisation" },
    "slug": "my-org"
  }
}

Request Body

string

required

Must be "create"

object

required

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

string

required

URL-friendly slug

object

Multilingual description

string

Organization website URL

string

Logo image URL

string

Cover image URL

string

Contact email

string

Contact phone number

object

Address object with streetAddress, addressLocality, postalCode, addressCountry

object

Legal name (multilingual)

string

Tax identification number

string

ISO 8601 date (YYYY-MM-DD)

number

Employee count

boolean

default:"true"

Organization is active

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
}

{
  "action": "toggle-featured",
  "organizationId": "org_123",
  "isFeatured": true
}

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

​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

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