> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Users & Organizations

> User account management, organization CRUD, member invitations, and role management.

# Users & Organizations

Manage user accounts, organizations, member invitations, and role assignments. Users can belong to multiple organizations with different roles.

## Authentication Endpoints

These endpoints do not require an existing access token.

### Register

<ParamField method="POST" path="/api/auth/register" />

Create a new user account with an optional organization.

#### Request Body

<ParamField body="email" type="string" required>User email address.</ParamField>
<ParamField body="password" type="string" required>Password (minimum 8 characters).</ParamField>
<ParamField body="displayName" type="string" required>Display name (1-255 characters).</ParamField>
<ParamField body="organizationName" type="string">Organization name. If provided, a new organization is created with the user as owner.</ParamField>

#### Response (201)

```json theme={null}
{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "displayName": "Jane Doe",
      "emailVerified": false,
      "accountType": "standard",
      "platformRole": "user",
      "isSuperAdmin": false,
      "status": "active",
      "organizations": [
        {
          "id": "uuid",
          "name": "My Workspace",
          "slug": "my-workspace",
          "role": "owner"
        }
      ]
    },
    "accessToken": "eyJ...",
    "refreshToken": "eyJ..."
  }
}
```

<Note>
  The first user to register on the platform is automatically promoted to `superadmin`.
</Note>

***

### Login

<ParamField method="POST" path="/api/auth/login" />

Authenticate with email and password.

#### Request Body

<ParamField body="email" type="string" required>User email address.</ParamField>
<ParamField body="password" type="string" required>User password.</ParamField>

#### Response (200)

Same shape as register response.

***

### Refresh Token

<ParamField method="POST" path="/api/auth/refresh" />

Exchange a valid refresh token for new access and refresh tokens.

#### Request Body

<ParamField body="refreshToken" type="string" required>Valid refresh token.</ParamField>

#### Response (200)

Same shape as register response with new tokens.

<Note>
  There is no server-side logout endpoint. Logout is performed client-side by discarding the stored access and refresh tokens.
</Note>

***

## User Profile

### Get Current User

<ParamField method="GET" path="/api/auth/me" />

Get the authenticated user's profile and organization memberships.

<Note>
  All API requests require a valid JWT token in the `Authorization: Bearer <token>` header. The API Gateway decodes the JWT and forwards auth context (`user-id`, `organization-id`, `user-email`, `x-platform-role`, `x-org-role`) as headers to downstream services.
</Note>

#### Response (200)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="User profile">
    <ResponseField name="id" type="string">User UUID.</ResponseField>
    <ResponseField name="email" type="string">Email address.</ResponseField>
    <ResponseField name="displayName" type="string">Display name.</ResponseField>
    <ResponseField name="emailVerified" type="boolean">Email verification status.</ResponseField>
    <ResponseField name="onboardingCompletedAt" type="string">ISO 8601 timestamp or null.</ResponseField>
    <ResponseField name="accountType" type="string">`standard` or `creator`.</ResponseField>
    <ResponseField name="platformRole" type="string">`user` or `superadmin`.</ResponseField>
    <ResponseField name="isSuperAdmin" type="boolean">Superadmin flag.</ResponseField>
    <ResponseField name="status" type="string">`active`, `suspended`, etc.</ResponseField>
    <ResponseField name="lastLoginAt" type="string">ISO 8601 timestamp.</ResponseField>

    <ResponseField name="organizations" type="object[]">
      Organization memberships.

      <Expandable title="Organization membership">
        <ResponseField name="id" type="string">Organization UUID.</ResponseField>
        <ResponseField name="name" type="string">Organization name.</ResponseField>
        <ResponseField name="slug" type="string">URL slug.</ResponseField>
        <ResponseField name="role" type="string">`owner`, `admin`, `editor`, or `viewer`.</ResponseField>
        <ResponseField name="tokenMarkupPercentage" type="number">Org-level markup.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://your-domain.com/api/auth/me \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://your-domain.com/api/auth/me", {
    headers: { Authorization: `Bearer ${token}` },
  });

  const { data } = await response.json();
  ```
</CodeGroup>

***

## Email Verification

### Verify Email

<ParamField method="POST" path="/api/auth/verify-email" />

Verify a user's email address using the token sent via email.

#### Request Body

<ParamField body="token" type="string" required>Email verification token.</ParamField>

***

### Resend OTP

<ParamField method="POST" path="/api/auth/resend-otp" />

Request a one-time password code sent to the user's email.

#### Request Body

<ParamField body="email" type="string" required>User email address.</ParamField>

***

### Verify OTP

<ParamField method="POST" path="/api/auth/verify-otp" />

Verify an OTP code.

#### Request Body

<ParamField body="email" type="string" required>User email address.</ParamField>
<ParamField body="otp" type="string" required>OTP code.</ParamField>

***

## Password Management

### Forgot Password

<ParamField method="POST" path="/api/auth/forgot-password" />

Request a password reset email.

#### Request Body

<ParamField body="email" type="string" required>User email address.</ParamField>

***

### Reset Password

<ParamField method="POST" path="/api/auth/reset-password" />

Complete a password reset using the token from the reset email.

#### Request Body

<ParamField body="token" type="string" required>Password reset token.</ParamField>
<ParamField body="password" type="string" required>New password (minimum 8 characters).</ParamField>

***

## Organization Management

<Note>
  All API requests require a valid JWT token in the `Authorization: Bearer <token>` header. The API Gateway decodes the JWT and forwards auth context (`user-id`, `organization-id`, `user-email`, `x-platform-role`, `x-org-role`) as headers to downstream services.
</Note>

### Update Organization

<ParamField method="PATCH" path="/api/auth/organizations/:id" />

Update organization settings.

#### Path Parameters

<ParamField path="id" type="string" required>Organization UUID.</ParamField>

#### Request Body

<ParamField body="name" type="string">Updated organization name.</ParamField>
<ParamField body="settings" type="object">Organization settings (e.g., `require_publish_approval`).</ParamField>

***

### List Organization Members

<ParamField method="GET" path="/api/auth/organizations/:id/members" />

Get all members of an organization with their roles.

#### Path Parameters

<ParamField path="id" type="string" required>Organization UUID.</ParamField>

#### Response (200)

<ResponseField name="members" type="object[]">
  <Expandable title="Member object">
    <ResponseField name="userId" type="string">User UUID.</ResponseField>
    <ResponseField name="email" type="string">Member email.</ResponseField>
    <ResponseField name="displayName" type="string">Display name.</ResponseField>
    <ResponseField name="role" type="string">`owner`, `admin`, `editor`, or `viewer`.</ResponseField>
    <ResponseField name="joinedAt" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

***

### Invite Member

<ParamField method="POST" path="/api/auth/invite" />

Send an invitation email to add a new member to the organization.

#### Request Body

<ParamField body="email" type="string" required>Email address to invite.</ParamField>
<ParamField body="role" type="string" default="editor">Role to assign: `admin`, `editor`, or `viewer`.</ParamField>

***

### Accept Invitation

<ParamField method="POST" path="/api/auth/accept-invitation" />

Accept an organization invitation using the token from the invitation email.

#### Request Body

<ParamField body="token" type="string" required>Invitation token.</ParamField>

***

### Update Member Role

<ParamField method="PATCH" path="/api/auth/organizations/:id/members/:userId" />

Change a member's role within the organization.

#### Path Parameters

<ParamField path="id" type="string" required>Organization UUID.</ParamField>
<ParamField path="userId" type="string" required>Member's user UUID.</ParamField>

#### Request Body

<ParamField body="role" type="string" required>New role: `admin`, `editor`, or `viewer`.</ParamField>

<Warning>
  Only organization owners and admins can change member roles. Owners cannot have their role changed.
</Warning>

***

### Remove Member

<ParamField method="DELETE" path="/api/auth/organizations/:id/members/:userId" />

Remove a member from the organization.

#### Path Parameters

<ParamField path="id" type="string" required>Organization UUID.</ParamField>
<ParamField path="userId" type="string" required>Member's user UUID.</ParamField>

***

## Organization Roles

| Role     | Permissions                                                     |
| -------- | --------------------------------------------------------------- |
| `owner`  | Full access. Cannot be removed. Only one per organization.      |
| `admin`  | Manage members, settings, and all resources.                    |
| `editor` | Create and edit agents, knowledge bases. Cannot manage members. |
| `viewer` | Read-only access to agents and conversations.                   |