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

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

cURL

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

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.

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

Mobile (Capacitor)

On iOS and Android, the app uses a native PKCE OAuth flow instead of browser redirects:

• POST /api/auth/native/social-init — begin the PKCE flow
• GET /api/auth/native/callback — receive the authorization code
• POST /api/auth/native/token-exchange — exchange the code for a session

These endpoints are only available when a social provider is configured on the server.

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.