Authentication

The ExtractForm API uses Bearer tokens. A global auth guard protects all routes unless marked public.

Token flow

1. POST /api/auth/register or POST /api/auth/login returns { user, accessToken, refreshToken, expiresIn }.
2. Send Authorization: Bearer <accessToken> on protected requests (default TTL: 15 minutes).
3. On 401, call POST /api/auth/refresh with { "refreshToken": "..." } to get a new token pair. Refresh tokens rotate; the old session is revoked.
4. POST /api/auth/logout with { "refreshToken" } revokes that session.
5. POST /api/auth/logout-all revokes all sessions (requires access token).

Register

curl -X POST http://localhost:4000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@example.com", "password": "securepass123"}'

Login

curl -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "password": "securepass123"}'

Refresh token

curl -X POST http://localhost:4000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'

API keys

API keys are ideal for automation, CI pipelines, and integrations like n8n.

Create an API key

Requires an access JWT (not an API key):

curl -X POST http://localhost:4000/api/auth/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production automation"}'

The plaintext apiKey (ef_live_…) is returned once. Store it securely.

Use an API key

Send the key as a Bearer token on any protected endpoint:

curl http://localhost:4000/api/jobs \
  -H "Authorization: Bearer ef_live_YOUR_KEY"

Manage keys

Method	Path	Description
GET	/api/auth/api-keys	List keys (metadata only, never full key)
DELETE	/api/auth/api-keys/:id	Revoke a key

• Key role cannot exceed your account role.
• Active keys per user capped by MAX_API_KEYS_PER_USER (default 25).
• Revoke immediately if a key is leaked.

Idempotency

Job creation endpoints accept an optional Idempotency-Key header. Repeating a request with the same key returns the original job instead of creating a duplicate.

curl -X POST http://localhost:4000/api/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: upload-invoice-001" \
  -F "file=@invoice.pdf" \
  -F "type=EXTRACTION" \
  -F "schemaId=YOUR_SCHEMA_ID"

Sessions

Method	Path	Description
GET	/api/auth/sessions	List active refresh sessions
DELETE	/api/auth/sessions/:id	Revoke one session
GET	/api/auth/me	Current user profile
GET	/api/auth/verify	Verify token is valid

Roles

Users have USER or ADMIN. Admin-only routes return 403 for other roles.

Public routes

These endpoints do not require authentication:

• POST /api/auth/register, /login, /refresh, /logout
• POST /api/schema/convert

Environment variables

Variable	Description
JWT_ACCESS_SECRET	Secret for access JWTs (required in production)
JWT_ACCESS_EXPIRES_IN	Access token TTL (default 15m)
JWT_REFRESH_EXPIRES_IN	Refresh session TTL (default 30d)
API_KEY_PREFIX	API key prefix (default ef_live_)
MAX_API_KEYS_PER_USER	Max active keys per user (default 25)