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 (a human-readable label) and one or more Access Keys — named signing key pairs created in the support console. Your app identifies itself with its access key, and each key carries its own 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 access key.
Your app verifies them locally with the access key's 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 access key's private key never leaves Authfy — you only handle the public key.
- Redirects only go to the Allowed URLs registered on your access key, 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, create and revoke access keys (with their 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 replacement access key, enabling a notification channel — contact your Authfy administrator.