Authentication

CutX supports magic link (passwordless) and GitHub OAuth authentication. All authenticated requests use JWT tokens.

Token Format

Tokens are issued as HS256 JWTs with a 7-day expiry. They can be sent two ways:

1. Cookie — cutx_token (HttpOnly, Secure, SameSite=Lax) — set automatically on login
2. Header — Authorization: Bearer <token>

Endpoints

Request Magic Link

POST /api/auth/magic-link
Content-Type: application/json

{ "email": "user@example.com" }

Sends a one-time login link to the user’s email. Rate limited to 1 request per email per 60 seconds. Token expires after 15 minutes.

Response (200):

{ "message": "Magic link sent" }

Verify Magic Link

GET /api/auth/verify?token=<token>

Verifies the token and creates a session. Redirects to /dashboard (existing user) or /onboarding (new user). New users receive 25 free credits and a welcome email.

GitHub OAuth

GET /api/auth/github

Redirects to GitHub for authorization. After approval, GitHub redirects to:

GET /api/auth/github/callback?code=<code>&state=<state>

Creates or links the user account and redirects to /dashboard.

Get Current User

GET /api/auth/me
Authorization: Bearer <token>

Response (200):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "User Name",
    "role": "user",
    "email_verified": true,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Logout

GET /api/auth/logout

Clears the session cookie and redirects to /login.

Protected Routes

Routes requiring authentication:

• /dashboard/**, /studio/**, /assets/**, /campaigns/**, /settings/**
• /api/products/**, /api/generate/**, /api/assets/**, /api/campaigns/**
• /api/credits/**, /api/inventory/**, /api/shows/**, /api/payouts/**

Public routes (no auth required):

• /, /login, /register, /pricing
• /api/auth/**, /api/demo/**

Error Responses

Status	Meaning
401	Missing or invalid token
403	Account suspended or banned
429	Rate limited (magic link: 60s cooldown)