Authentication

Bearer Token (Session Auth)

Used by: chat widget, business console, and any browser-based application where a user signs in directly.

How it works

1. Sign in via POST /auth/login with your email and password.
2. A session cookie is set automatically. It is scoped to .maison-labs.com and is shared across all subdomains.
3. Subsequent requests carry the cookie automatically in browser environments.

You can also send the token explicitly as an Authorization header instead of a cookie:

curl https://maison-labs.com/auth/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Check session validity

Call GET /auth/ to verify whether the current session is valid:

# 200 → session valid
# 401 → session missing or expired
curl https://maison-labs.com/auth/

API Key

Used by: external integrations, A2A agents, MCP clients, and server-to-server calls.

Key format

Keys follow the pattern mx_{env}_{base64url_payload}. For example: mx_p_UER3NVky... where the middle segment identifies the environment. Send the key in the x-api-key request header.

Create an API key

Key creation requires an active session — you must be signed in. Call PUT /api/user/apikey:

curl -X PUT https://maison-labs.com/api/user/apikey \
  -H "Cookie: session=YOUR_TOKEN" \
  -H "Content-Type: application/json"

Send requests with an API key

Always pair the API key with the x-client-id header for client-scoped operations:

curl -X POST https://maison-labs.com/api/message \
  -H "x-api-key: mx_p_YOUR_KEY" \
  -H "x-client-id: YOUR_CLIENT_UUID" \
  -H "Content-Type: application/json" \
  -d '{"query": "What time is checkout?"}'

Revoke a key

Delete a key by its ID using DELETE /api/user/apikey/:id. Deletion is immediate and permanent.

curl -X DELETE https://maison-labs.com/api/user/apikey/KEY_ID \
  -H "Cookie: session=YOUR_TOKEN"

Method precedence