Quick Start

Get ezAuth running locally and authenticate your first user in under 5 minutes.

Prerequisites

1. Start Infrastructure

Start PostgreSQL and Redis using the included Docker Compose file:

docker compose up -d

This starts PostgreSQL 16 on port 5432 and Redis 7 on port 6379.

2. Install & Configure

# Install the ezAuth package
pip install -e .

# Copy and edit the environment file
cp .env.example .env

# Run database migrations
alembic upgrade head

# Start the server
uvicorn ezauth.main:app --reload --port 8000 --proxy-headers

The API is now running at http://localhost:8000. The interactive API docs are at http://localhost:8000/docs.

3. Create a Tenant & Application

Open the admin dashboard at http://localhost:8000/dashboard. There is no shared dashboard password: enter an address listed in DASHBOARD_ADMIN_EMAILS (or an application’s owner_email) and ezAuth emails you a single-use login code. Then:

  1. Create a Tenant (e.g., "My Company")
  2. Create an Application within the tenant (e.g., "My App - Dev")
  3. Copy the publishable key (pk_...) and secret key (sk_...)

4. Add Auth to Your Frontend

import { EZAuth } from '@ezauth/client'

const ez = new EZAuth({
  baseUrl: 'http://localhost:8000',
  publishableKey: 'pk_dev_...',
})

// Sign up a new user
await ez.auth.signUp({
  email: '[email protected]',
  password: 's3cret',
})

// Check email for 6-digit code, then verify
const session = await ez.auth.verifyCode({
  email: '[email protected]',
  code: '123456',
})

// Sign in with password
const session = await ez.auth.signIn({
  email: '[email protected]',
  password: 's3cret',
})

// Get current user
const me = await ez.auth.getSession()
console.log(me.email)
from ezauth_client import EZAuth

ez = EZAuth(
    base_url="http://localhost:8000",
    publishable_key="pk_dev_...",
)

# Sign up
ez.auth.sign_up("[email protected]", password="s3cret")

# Verify code from email
session = ez.auth.verify_code("[email protected]", "123456")

# Sign in
session = ez.auth.sign_in("[email protected]", password="s3cret")
# Sign up
curl -X POST http://localhost:8000/v1/signups \
  -H "X-Publishable-Key: pk_dev_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "s3cret"}'

# Verify code
curl -X POST http://localhost:8000/v1/verify-code \
  -H "X-Publishable-Key: pk_dev_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "code": "123456"}'

# Sign in with password
curl -X POST http://localhost:8000/v1/signins \
  -H "X-Publishable-Key: pk_dev_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "s3cret", "strategy": "password"}'

# Get current user
curl http://localhost:8000/v1/me \
  -H "Authorization: Bearer <access_token>"

5. Backend Admin Operations

Use the secret key for server-side operations:

import { EZAuth } from '@ezauth/client'

const ez = new EZAuth({
  baseUrl: 'http://localhost:8000',
  secretKey: 'sk_dev_...',
})

// List all users
const { users, total } = await ez.users.list({ limit: 10 })

// Create a user (skips email verification)
const user = await ez.users.create({ email: '[email protected]' })

// Create a sign-in token (for server-to-server auth)
const token = await ez.sessions.createSignInToken({ userId: user.id })

6. Verify JWTs in Your Backend

Use the Python Server SDK to verify ezAuth JWTs in your own API:

from fastapi import FastAPI
from ezauth_sdk import EZAuthMiddleware

app = FastAPI()
app.add_middleware(
    EZAuthMiddleware,
    auth_domain="http://localhost:8000",
    public_paths=["/health"],
)

@app.get("/protected")
async def protected(request):
    auth = request.state.auth
    return {"user_id": auth.user_id}

Next Steps