Architecture
This page explains the concepts you'll meet everywhere else in these docs.
The three building blocks
- Users are people. A user has one account — one email, one password — shared across every application connected to Authfy.
- Companies are organizations. Users are members of one or more
companies, with a role in each (
OWNER,ADMIN, orMEMBER). - Applications are your apps. Each application registered with Authfy has
a unique App ID (its OAuth
client_id), its own signing key pair, and a list of Allowed URLs it may redirect to.
Access is the intersection of the three: a user can use your application when they are an active member of a company that is subscribed to it. A subscription can cover the whole company, or only selected categories (teams/departments) within it.
How sign-in works
When a user clicks "Sign in" in your app:
- Your app sends them to Authfy's hosted sign-in page (the
authfynpm package builds this redirect for you, with PKCE protection). - The user authenticates with Authfy — your app never sees their password.
- Authfy checks which of the user's companies is subscribed to your application and resolves the company for this session automatically.
- The user is redirected back to your app with a one-time code, which your app's backend exchanges for tokens.
Your app receives:
- an access token — proves who the user is and which company they're acting in; sent with every API call;
- an ID token — the user's profile (name, email) in OpenID Connect format;
- a refresh token — lets your app renew the session silently without asking the user to sign in again.
Access and ID tokens are RS256-signed JWTs, signed with your application's
own key. Your app verifies them locally with your application public key —
no network call needed. The important claims are sub (user), company_id /
company_slug (the resolved company), email, and name — the full list is
in JWT verification.
Sessions
Authfy keeps one shared activity session per user across all connected apps. As long as the user is active in any connected app, silent token refresh keeps working everywhere; once they go idle everywhere, sessions expire together. Signing out can end just your app's session or the whole SSO session.
What stays on the platform
Some things are deliberately not your app's problem:
- Passwords never reach your application.
- The application private key never leaves Authfy — you only handle the public key.
- Redirects only go to your registered Allowed URLs, blocking token hijacking.
- Company membership and roles are managed centrally by administrators; your app just reads them.
- Every administrative change is recorded in an audit trail.
Who does what
| Task | Who |
|---|---|
| Register applications, manage keys and Allowed URLs | Authfy administrator |
| Create companies, manage members, subscriptions, categories | Authfy administrator (or your backend, via the Management API) |
| Sign users in, verify tokens, read directory data | Your application |
| Send transactional email/SMS | Your application, via the notification API |
If you need something changed that isn't covered by the APIs here — a new application registration, a key reset, enabling a notification channel — contact your Authfy administrator.