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

# Authentication

> Session cookies, social login, and bot token authentication

MeepaChat handles authentication via a sidecar service that manages user accounts, session cookies, and social login.

## Human users

### Email/password

The default login method. The client `POST`s credentials to `/api/auth/login`, which validates them and sets an HTTP-only session cookie. All subsequent requests include the cookie automatically.

### Social login

When configured, users can sign in via Google, GitHub, or Discord:

1. Client calls `POST /api/auth/social` with the chosen provider
2. User is redirected to the provider's OAuth page
3. Provider redirects back to `/api/auth/callback/*`
4. The server exchanges the code and sets a session cookie

Which providers are available depends on server configuration. Query the auth config endpoint to find out:

```
GET /api/auth/config
```

```json theme={null}
{
  "data": {
    "directLoginEnabled": true,
    "openRegistration": true,
    "requireEmailVerification": false,
    "socialProviders": ["google", "github"]
  }
}
```

| Field                      | Description                                                    |
| -------------------------- | -------------------------------------------------------------- |
| `directLoginEnabled`       | `true` if email/password login is available                    |
| `openRegistration`         | `true` if self-registration is open; `false` means invite-only |
| `requireEmailVerification` | `true` if the email must be verified before login              |
| `socialProviders`          | Enabled OAuth providers                                        |

### Session storage

Sessions are stored in HTTP-only cookies. The default TTL is 30 days. Cookies are tied to the server's configured domain and are not accessible via JavaScript.

## Auth endpoints

| Method | Path                    | Description                       | Rate limited   |
| ------ | ----------------------- | --------------------------------- | -------------- |
| `GET`  | `/api/auth/config`      | Fetch auth configuration (public) | No             |
| `POST` | `/api/auth/login`       | Email/password login              | Yes — stricter |
| `POST` | `/api/auth/register`    | Register a new account            | Yes — stricter |
| `POST` | `/api/auth/logout`      | Clear session cookie              | Yes — stricter |
| `POST` | `/api/auth/social`      | Initiate social login             | Yes — stricter |
| `GET`  | `/api/auth/callback/*`  | OAuth callback                    | Yes — stricter |
| `GET`  | `/api/auth/get-session` | Return current session            | No             |
| `GET`  | `/api/auth/me`          | Return current user profile       | No             |

The login and register endpoints have a stricter rate limit (10 req/min, burst 5) than the global limit. See [Rate Limiting](/meepachat/rate-limiting) for details.

## Bot authentication

Bots use token-based authentication via the `Authorization` header instead of session cookies.

**Token format:** `botID.secret` (a dot-separated ID and secret)

**Header:**

```
Authorization: Bot <botID>.<secret>
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://chat.example.com/api/servers/123/channels/456/messages \
    -H "Authorization: Bot 789.a1b2c3d4e5f6" \
    -H "Content-Type: application/json" \
    -d '{"content": "Hello from a bot"}'
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch('/api/servers/123/channels/456/messages', {
    method: 'POST',
    headers: {
      'Authorization': 'Bot 789.a1b2c3d4e5f6',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ content: 'Hello from a bot' }),
  });
  ```
</CodeGroup>

Bot tokens are issued when a bot is created via `POST /api/bots`. The token is only shown once — store it securely. If lost or compromised, regenerate it via `POST /api/bots/{botID}/regenerate-token`. The old token is invalidated immediately on regeneration.

Bots can access the same resource endpoints as human users (servers, channels, messages, reactions) but cannot access bot management endpoints or WebSocket connections intended for human clients.

<Warning>
  Never commit bot tokens to source control or include them in client-side code. Treat them like passwords.
</Warning>

## Mobile App

The MeepaChat mobile app is available on iOS via [TestFlight](https://testflight.apple.com/join/XXXXX). It connects to your self-hosted instance — just enter your server URL when signing in.

## WebSocket authentication

The WebSocket endpoint (`/api/ws`) requires authentication. The server reads the session cookie via `SessionCookieToHeader` middleware, which promotes the cookie to an `Authorization` header before the auth check runs. No separate token is needed for WebSocket connections from a browser.