> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Ishaq74/concordia/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations API

> Manage organizations, members, invitations, and profiles

## 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`:

<CodeGroup>
  ```bash GET Request theme={null}
  curl "https://your-domain.com/api/admin/organizations?includeMembers=true" \
    -H "Authorization: Bearer <token>"
  ```

  ```json Response theme={null}
  {
    "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"
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

#### Query Parameters

<ParamField query="organizationId" type="string">
  Fetch single organization by ID (includes members)
</ParamField>

<ParamField query="includeMembers" type="boolean" default="false">
  Include member list for each organization
</ParamField>

***

### Create Organization

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

<CodeGroup>
  ```bash POST Request theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "organization": {
      "id": "org_789",
      "name": "My Organization",
      "slug": "my-org",
      "createdAt": "2024-03-03T15:00:00Z"
    }
  }
  ```
</CodeGroup>

#### Request Body

<ParamField body="action" type="string" required>
  Must be `"create"`
</ParamField>

<ParamField body="name" type="string" required>
  Organization name
</ParamField>

<ParamField body="slug" type="string" required>
  URL-friendly organization slug (unique)
</ParamField>

***

### Set Active Organization

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

```json theme={null}
{
  "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`:

```bash theme={null}
GET /api/admin/organizations/members?organizationId=org_123
```

#### Response

```json theme={null}
{
  "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`:

<CodeGroup>
  ```bash POST Request theme={null}
  curl -X POST "https://your-domain.com/api/admin/organizations/members" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d @invite.json
  ```

  ```json invite.json theme={null}
  {
    "action": "invite",
    "organizationId": "org_123",
    "email": "newmember@example.com",
    "role": "member"
  }
  ```

  ```json Response theme={null}
  {
    "invitation": {
      "id": "inv_002",
      "organizationId": "org_123",
      "email": "newmember@example.com",
      "role": "member",
      "status": "pending",
      "expiresAt": "2024-03-17T10:00:00Z"
    }
  }
  ```
</CodeGroup>

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

<ParamField body="action" type="string" required>
  Must be `"invite"`
</ParamField>

<ParamField body="organizationId" type="string" required>
  Organization ID
</ParamField>

<ParamField body="email" type="string" required>
  Email address to invite
</ParamField>

<ParamField body="role" type="string" default="member">
  Member role: `owner`, `admin`, `member`
</ParamField>

***

### Update Member Role

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

```json theme={null}
{
  "action": "update-role",
  "organizationId": "org_123",
  "memberId": "mem_002",
  "role": "admin"
}
```

***

### Remove Member

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

```json theme={null}
{
  "action": "remove-member",
  "organizationId": "org_123",
  "memberId": "mem_002"
}
```

***

### Cancel Invitation

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

```json theme={null}
{
  "action": "cancel-invitation",
  "organizationId": "org_123",
  "invitationId": "inv_001"
}
```

***

### Add Existing User as Member

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

```json theme={null}
{
  "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`:

```bash theme={null}
GET /api/admin/organizations/profile
```

#### Response

```json theme={null}
{
  "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

```bash theme={null}
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`:

<CodeGroup>
  ```bash POST Request theme={null}
  curl -X POST "https://your-domain.com/api/admin/organizations/profile" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d @org-profile.json
  ```

  ```json org-profile.json theme={null}
  {
    "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
  }
  ```

  ```json Response theme={null}
  {
    "organization": {
      "id": "org_999",
      "name": { "fr": "Mon Organisation" },
      "slug": "my-org"
    }
  }
  ```
</CodeGroup>

#### Request Body

<ParamField body="action" type="string" required>
  Must be `"create"`
</ParamField>

<ParamField body="name" type="object" required>
  Multilingual name object (e.g., `{ "fr": "...", "en": "..." }`)
</ParamField>

<ParamField body="slug" type="string" required>
  URL-friendly slug
</ParamField>

<ParamField body="description" type="object">
  Multilingual description
</ParamField>

<ParamField body="url" type="string">
  Organization website URL
</ParamField>

<ParamField body="logo" type="string">
  Logo image URL
</ParamField>

<ParamField body="image" type="string">
  Cover image URL
</ParamField>

<ParamField body="email" type="string">
  Contact email
</ParamField>

<ParamField body="telephone" type="string">
  Contact phone number
</ParamField>

<ParamField body="address" type="object">
  Address object with `streetAddress`, `addressLocality`, `postalCode`, `addressCountry`
</ParamField>

<ParamField body="legalName" type="object">
  Legal name (multilingual)
</ParamField>

<ParamField body="taxID" type="string">
  Tax identification number
</ParamField>

<ParamField body="foundingDate" type="string">
  ISO 8601 date (YYYY-MM-DD)
</ParamField>

<ParamField body="numberOfEmployees" type="number">
  Employee count
</ParamField>

<ParamField body="isActive" type="boolean" default="true">
  Organization is active
</ParamField>

<ParamField body="isFeatured" type="boolean" default="false">
  Mark as featured
</ParamField>

***

### Update Organization Profile

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

```json theme={null}
{
  "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`:

<CodeGroup>
  ```json Toggle Active theme={null}
  {
    "action": "toggle-active",
    "organizationId": "org_123",
    "isActive": false
  }
  ```

  ```json Toggle Featured theme={null}
  {
    "action": "toggle-featured",
    "organizationId": "org_123",
    "isFeatured": true
  }
  ```
</CodeGroup>

***

### Delete Organization Profile

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

```json theme={null}
{
  "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`:

```typescript theme={null}
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            |

***

## Related Resources

<CardGroup cols={2}>
  <Card title="API Overview" icon="globe" href="/development/api/overview">
    Authentication and security
  </Card>

  <Card title="Better Auth Orgs" icon="arrow-up-right-from-square" href="https://www.better-auth.com/docs/plugins/organization">
    Better Auth organization plugin docs
  </Card>
</CardGroup>