Authentication

FreeMaint accepts two auth mechanisms: JWTs (issued by /auth/login, used by our web and mobile apps) and API keys (created in /company-settings/api, used by your own integrations).

JWT (user sessions)

1. POST /auth/login — Body: {email, password}. Returns {access_token, refresh_token}.
2. Send Authorization header — On every request: Authorization: Bearer <access_token>.
3. Refresh when expired — POST /auth/refresh with the refresh_token to get a new access_token. Access tokens last 2 hours.

API key (server integrations)

1. Open /company-settings/api — Visible to admins from Business tier upward.
2. Click 'New key' — Optionally set an expiration. The raw key is shown ONCE — copy it immediately.
3. Use it — Send Authorization: Bearer fmk_<rawKey> on every request. Format: starts with fmk_ followed by 32 hex characters.

Security notes

• API keys are stored as SHA-256 hashes — once you close the reveal dialog, the raw value is unrecoverable
• Revoking a key disables it immediately; the row is kept for audit
• Each key is scoped to a single company; cross-tenant requests always 401
• Keys can have an optional expiresAt for short-lived integrations