Skip to content
Truss Docs

Authentication

Truss provides authentication out of the box, powered by Ory Kratos. The dashboard gives you a GUI for managing users, sessions, and login providers. Everything is also available via API.

Setup

Set these environment variables in apps/api/.env:

KRATOS_PUBLIC_URL=http://localhost:4433
KRATOS_ADMIN_URL=http://localhost:4434
KRATOS_ADMIN_TOKEN=your-admin-token
TRUSS_AUTH_REQUIRED=true

With TRUSS_AUTH_REQUIRED=true, the dashboard requires login. Set to false for local development without auth.

Dashboard login flow

Truss uses Kratos API flows (not browser flows) to avoid CSRF issues when proxying. The flow:

  1. Frontend calls GET /api/auth/login to initialize a login flow
  2. User submits credentials via POST /api/auth/login
  3. Server stores the session token in an HttpOnly cookie (truss_session)
  4. Subsequent requests are authenticated via the cookie

Managing identities

List users

Terminal window
curl http://localhost:8787/api/auth/identities \
  -H "Cookie: truss_session=your-session-token"

Create a user

Terminal window
curl -X POST http://localhost:8787/api/auth/identities \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

Batch import users

Terminal window
curl -X POST http://localhost:8787/api/auth/users/import \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {"email": "alice@example.com", "password": "pass1234"},
      {"email": "bob@example.com", "password": "pass5678"}
    ]
  }'

Up to 500 users per batch.

Activate/deactivate a user

Terminal window
curl -X PATCH http://localhost:8787/api/auth/identities/{id}/state \
  -H "Content-Type: application/json" \
  -d '{"state": "inactive"}'

Reset a password

Terminal window
curl -X POST http://localhost:8787/api/auth/identities/{id}/reset-password \
  -H "Content-Type: application/json" \
  -d '{"password": "newpassword123"}'

Social login providers

Configure social login by setting the KRATOS_OIDC_PROVIDERS env var:

KRATOS_OIDC_PROVIDERS=google,github

Supported providers: Google, GitHub, Discord, Apple, Microsoft. Custom OIDC providers are also supported.

Check configured providers:

Terminal window
curl http://localhost:8787/api/auth/providers

Client API

The client API at /v1/auth/identities provides identity management for external tools:

Terminal window
# List identities (requires service_role key)
curl http://localhost:8787/v1/auth/identities \
  -H "apikey: truss_sk_your_key"


# Get identity detail
curl http://localhost:8787/v1/auth/identities/{id} \
  -H "apikey: truss_sk_your_key"

Session management

View and revoke active sessions from the dashboard or via API:

Terminal window
# List active sessions
curl http://localhost:8787/api/auth/sessions


# Revoke a session
curl -X DELETE http://localhost:8787/api/auth/sessions/{id}


# Force-logout a user (revoke all their sessions)
curl -X DELETE http://localhost:8787/api/auth/identities/{id}/sessions