Service API Reference

Auth: Authorization: Bearer <api_key>

Resolves a user session into an authorization decision. Single CTE query: session → user → roles → role permissions → direct overrides → merged set → optional policy evaluation.

Request Body

* Provide token (session-based) or access_token (JWT-based), not both.

Response

{
  "authenticated": true,
  "user": { "id": "...", "email": "...", "name": "...", "tenant_id": "..." },
  "granted": true,           // present if "permission" was requested
  "grants": { "perm": true },// present if "permissions" batch was requested
  "permissions": ["..."],    // present if include contains "permissions"
  "roles": ["..."],          // present if include contains "roles"
  "feature_flags": { "flag": true } // present if include contains "flags"
}

curl Example

curl -X POST https://orbit.example.com/check \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "user-session-token",
    "tenant_id": "tenant-uuid",
    "permission": "documents.edit",
    "resource": { "owner_id": "user-123" }
  }'

# Step 1: Login (no tenant_id → pre-tenant session)
curl -X POST https://orbit.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "admin@example.com", "password": "secret" }'
# → { "token": "pre-token", "expires_at": "...", "next": "tenant_select" }

# Step 2: List memberships
curl https://orbit.example.com/auth/memberships \
  -H "Authorization: Bearer ${PRE_TOKEN}"
# → { "data": [{ "tenant_id": "...", "tenant_slug": "acme", "tenant_name": "Acme Corp", "roles": ["admin"] }] }

# Step 3: Exchange for tenant-scoped session
curl -X POST https://orbit.example.com/auth/session/exchange \
  -H "Authorization: Bearer ${PRE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_slug": "acme" }'
# → { "token": "tenant-scoped-token", "expires_at": "...", "next": "complete" }