REST & Auth API

While the platform's primary interface is GraphQL, several services expose REST endpoints for authentication flows, content feeds, admin metrics, and SCIM provisioning.

Dev Token (Quick Auth)

The fastest way to get an authenticated session for API testing: no OAuth, no browser required.

# Issue a session token for any seeded user
curl -s -X POST http://localhost:3008/auth/dev/token \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}' | jq .

{
	"session_token": "sess_a1b2c3d4...",
	"expires_in": 86400,
	"user": { "id": "...", "email": "user@example.com", "username": "user" }
}

Requires DEV_MODE=true in the auth service. Enabled by default in local development.

Use the token in subsequent requests:

export TOKEN="sess_a1b2c3d4..."

# GraphQL
curl http://localhost:30000/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id email } }"}'

# REST (auth service)
curl http://localhost:3008/me \
  -H "Cookie: session_token=$TOKEN"

Auth Service (`localhost:3008`)

OAuth Flows

# Initiate Google OAuth (open in browser)
open "http://localhost:3008/auth/oauth/google"

Email OTP (Passwordless)

# Start email login
curl -X POST http://localhost:3008/auth/email/login/start \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Verify OTP
curl -X POST http://localhost:3008/auth/email/login/finish \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "code": "123456"}'

Magic Links

Passkeys (WebAuthn)

MFA (Two-Factor)

Mobile Token Exchange

For native mobile apps (React Native / KMP) that handle OAuth client-side:

# Exchange a Google access token for session tokens
curl -X POST http://localhost:3008/auth/mobile/token \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "access_token": "ya29.a0AfH6..."
  }'

Response:

{
	"session_token": "sess_...",
	"refresh_token": "ref_...",
	"expires_in": 900,
	"refresh_expires_in": 2592000,
	"user": { "id": "...", "email": "..." }
}

SAML SSO

Session Validation

Gateway (`localhost:30000`)

Content Feeds

# Get RSS feed for a Malet
curl http://localhost:30000/rss/m/my-coffee-shop/blogs.xml

Admin Metrics

# JSON metrics
curl http://localhost:30000/admin/metrics | jq .

# Prometheus format
curl http://localhost:30000/admin/metrics/prometheus

GraphQL

See the GraphQL API guide for full details.

SCIM Service (`localhost:3019`)

SCIM 2.0 (RFC 7644) for enterprise user provisioning. Requires a SCIM bearer token generated via the Organizations GraphQL API.

Discovery

Users

# List SCIM users (requires SCIM token)
curl http://localhost:3019/scim/v2/Users \
  -H "Authorization: Bearer scim_token_here"

# Filter by username
curl "http://localhost:3019/scim/v2/Users?filter=userName%20eq%20%22john%22" \
  -H "Authorization: Bearer scim_token_here"

Groups (Stub)

Auth Flow Summary

┌──────────────┐        ┌──────────────┐       ┌──────────────┐
│   Browser    │        │ Auth Service │       │   Gateway    │
│  (Frontend)  │        │  (:3008)     │       │  (:30000)    │
└──────┬───────┘        └──────┬───────┘       └──────┬───────┘
       │                       │                      │
       │  GET /auth/oauth/     │                      │
       │  google ─────────────>│                      │
       │                       │                      │
       │  <── redirect to ─────│                      │
       │      Google           │                      │
       │                       │                      │
       │  callback + cookie ──>│                      │
       │  <── session_token ───│                      │
       │      (Set-Cookie)     │                      │
       │                       │                      │
       │  POST /graphql ───────┼──────────────────────>│
       │  (Cookie: session_t)  │  GET /auth/validate  │
       │                       │<──────────────────────│
       │                       │  {user_id, email}     │
       │                       │──────────────────────>│
       │                       │                      │
       │  <── GraphQL response─┼──────────────────────│
       │                       │                      │

── API / CLI Flow ─────────────────────────────────────

┌──────────┐            ┌──────────────┐       ┌──────────────┐
│  curl /  │            │ Auth Service │       │   Gateway    │
│ Postman  │            │  (:3008)     │       │  (:30000)    │
└────┬─────┘            └──────┬───────┘       └──────┬───────┘
     │                         │                      │
     │ POST /auth/dev/token ──>│                      │
     │ {"email": "..."}        │                      │
     │ <── session_token ──────│                      │
     │                         │                      │
     │ POST /graphql ──────────┼──────────────────────>│
     │ (Bearer: session_t)     │  POST /validate-token│
     │                         │<──────────────────────│
     │                         │  {user_id, email}     │
     │                         │──────────────────────>│
     │                         │                      │
     │ <── GraphQL response ───┼──────────────────────│