Auth API

Authentication endpoints for magic link email auth.

Base path: /api/v1/auth

Sign Up

POST /api/v1/auth/signup
Content-Type: application/json

{ "email": "[email protected]" }

Creates a new user (or reuses existing) and sends a magic link. The response does not reveal whether the email was already registered.

Response (200)

{ "ok": true, "message": "If this email is valid, a magic link has been sent." }

Log In

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "[email protected]" }

Sends a magic link to an existing user. Rate limited to 3 requests per email per 15-minute window.

Response (200)

{ "ok": true, "message": "If this email is registered, a magic link has been sent." }

Response (429)

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many magic link requests. Try again later.",
    "status": 429
  }
}

Verify Magic Link

GET /api/v1/auth/verify?token={token}

Verifies a magic link token and creates a session. Tokens are single-use and expire after 15 minutes.

• If Accept: application/json header is set, returns JSON
• Otherwise, redirects to the dashboard

Response (200)

{ "ok": true, "message": "Authenticated successfully" }

Sets __Host-session cookie (httpOnly, secure, SameSite=Lax, 30-day expiry).

Get Current User

GET /api/v1/auth/me

Returns the authenticated user's profile based on the session cookie. No Authorization header needed.

Response (200)

{ "id": "user_01abc...", "email": "[email protected]", "created_at": "2026-01-01T00:00:00Z" }

Response (401)

Returned when no valid session cookie is present.

Log Out

POST /api/v1/auth/logout

Destroys the current session and clears the session cookie.

Response (200)

{ "ok": true, "message": "Logged out successfully" }