Authentication

All API routes require authentication. (Public access at data model level.) The platform supports three authentication methods.

1. Login (JWT Token)

Exchange credentials for a short-lived access token and a refresh token.

POST /api/auth/login

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

const res = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com', password: 'secret' }),
})
const { data } = await res.json()
// data.access_token, data.refresh_token, data.expires (milliseconds)

Response:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "v1.AAAA...",
    "expires": 3600000
  }
}

Using the token

Include the access token in the Authorization header on every subsequent request:

Authorization: Bearer <access_token>

Refreshing the token

Access tokens expire according to your Supabase JWT config (default: 1 hour). Use the refresh token to get a new pair:

POST /api/auth/refresh

{ "refresh_token": "v1.AAAA..." }

2. Session Cookie (Browser)

When logging in from a browser, the platform automatically sets secure httpOnly cookies. Subsequent requests from the same browser include the cookie automatically — no manual token management needed.

3. Static Token (API Keys)

Static tokens are long-lived API keys that don’t expire. They are ideal for CI/CD pipelines, server-to-server integrations, and automation scripts.

Generate a token

Via the UI: Users → Edit User → Generate Token → Save

Via the API:

# 1. Generate a random string
curl "https://your-domain.com/api/utils/random/string?length=32" \
  -H "Authorization: Bearer <admin_token>"
 
# 2. Assign it to a user
curl -X PATCH "https://your-domain.com/api/users/<user_id>" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"token": "<generated_string>"}'

Use the static token

curl https://your-domain.com/api/items/posts \
  -H "Authorization: Bearer <static_token>"

Password Reset

POST /api/auth/password/request   → sends reset email
  Body: { email }

POST /api/auth/password/reset     → completes reset with token from email
  Body: { token, password }

Current User

GET /api/auth/user

Returns the authenticated user’s profile and role information.

Logout

POST /api/auth/logout

Invalidates the current session server-side. Scope depends on how you authenticate:

• Bearer token (Authorization header) — only the session for that specific token is revoked; other active sessions on other devices are unaffected.
• Session cookie (browser) — all sessions for the user are revoked across all devices.

Bearer token clients must pass the token in the Authorization header so the server knows which session to revoke. Omitting the header falls back to cookie-based session logout.

curl -X POST https://your-domain.com/api/auth/logout \
  -H "Authorization: Bearer <access_token>"

await fetch('/api/auth/logout', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}` },
})

Error Responses

All auth errors follow the standard error envelope:

{
  "errors": [
    {
      "message": "Invalid user credentials",
      "extensions": { "code": "INVALID_CREDENTIALS" }
    }
  ]
}