Authentication

Two layers of auth in Mosaic. Platform auth is the X-API-Key header that authenticates you as a Mosaic user. User auth is the built-in endpoint set that authenticates your app's end-users.

Platform auth — the API key

Every Mosaic user gets one API key on signup. It goes in the X-API-Key header on every request:

Base URL:  https://api.mosaic.site/v1/project
Header:    X-API-Key: mk_xxxxxxxxxxxx

curl $API/projects -H "X-API-Key: $MOSAIC_API_KEY"

Where to find it: Dashboard → Settings → API Key. Or fetch it programmatically:

# After dashboard login, with a JWT bearer:
curl https://api.mosaic.site/api/auth/me -H "Authorization: Bearer $JWT"

# Regenerate a fresh key (invalidates the old one)
curl -X POST https://api.mosaic.site/api/auth/regenerate-api-key \
  -H "Authorization: Bearer $JWT"

User auth — for your app's users

Mosaic ships a complete end-user auth system inside every project. No setup, no provider to wire up — auth tables auto-create on first use.

Password auth

# Sign up
curl -X POST $API/{slug}/auth/signup \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass123","name":"Alice"}'

# Log in
curl -X POST $API/{slug}/auth/login \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass123"}'

Passwords are hashed with Argon2. Minimum length: 8 characters.

Magic link (passwordless)

curl -X POST $API/{slug}/auth/send-magic-link \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "redirect_url": "https://yourapp.mosaic.site/dashboard",
    "name": "Alice"
  }'

User clicks the link in email, lands at yourapp.com/dashboard?user_id=xxx&verified=true. Tokens expire after 15 minutes.

Password reset

# Step 1: send reset email
curl -X POST $API/{slug}/auth/reset-password \
  -H "X-API-Key: $KEY" \
  -d '{"email":"user@example.com","redirect_url":"https://yourapp.com/reset"}'

# Step 2: user clicks link, completes reset
curl -X POST $API/{slug}/auth/reset-password/confirm \
  -d '{"token":"token-from-email","new_password":"newsecure123"}'

User management

# List, get, update, delete
curl "$API/{slug}/auth/users?limit=50&verified_only=true" -H "X-API-Key: $KEY"
curl $API/{slug}/auth/users/{user_id} -H "X-API-Key: $KEY"
curl -X PATCH $API/{slug}/auth/users/{user_id} \
  -H "X-API-Key: $KEY" \
  -d '{"name":"New Name","metadata":{"role":"admin"}}'

Endpoints