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
• Access levels: READ (queries only), READ_STOCK (queries + adjustStock — ideal for a consume-only kiosk), FULL (default — all operations)

Testing an integration

There is no separate sandbox environment: an API key always addresses the real data of the company it belongs to. Two ways to test safely. (1) Sign up a second, free company and use it as your test tenant — the isolation between companies is the same mechanism that separates every customer, so nothing you do there can reach your production data. (2) For read-only work, create a key with the READ access level: it can run every query and no mutation, so it cannot change anything at all. When you are ready to write, a READ_STOCK key allows adjustStock and nothing else.