Authentication model
How SimpleAuth handles users, sessions, and API keys.
SimpleAuth is a hosted auth backend. Your app talks to a single API — /api/external/auth/* on https://simpleauth.net — and SimpleAuth takes care of passwords, sessions, email verification, and admin operations.
You rarely need to call the API directly. The JavaScript SDK wraps every endpoint, and the React package scaffolds hooks and UI on top of that.
Sessions
When a user signs in, SimpleAuth sets two HTTP-only cookies on the response:
sa_ext_session— identifies the active session.sa_ext_app— identifies which application the session belongs to.
Because they are HttpOnly, JavaScript can neither read nor tamper with them. The SDK sends them automatically on every request (credentials: "include"), so authenticated calls like auth.me() and auth.logout() just work in the browser — no tokens to pass around.
CORS and cookies
For cookies to travel between your frontend and the SimpleAuth API, your app origin must be allowlisted in the dashboard. See Keys and security for the full checklist.
API keys
Every request is scoped to an application with an API key in the Authorization header.
- Public key (
sa_live_…) — used from browsers and mobile clients. Can register users, sign in, verify email, and reset passwords. - Secret key (
sa_secret_…) — used only from your backend. Does everything the public key can, plus admin actions such as banning users or revoking sessions.
See Keys and security for when to use each.
The three layers
A typical SimpleAuth-powered app has three layers:
| Layer | Runs on | Uses |
|---|---|---|
| Frontend | Browser / mobile | Public key + session cookies |
| Backend (optional) | Your server | Secret key for admin actions |
| SimpleAuth API | https://simpleauth.net | Manages users, sessions, email |
Most apps only need the frontend layer. Reach for the server SDK when you want to create users server-side, ban accounts, or revoke sessions.
Building with React
If you are on React or Next.js, the @simpleauthjs/react CLI scaffolds everything the model above implies — a configured client, provider, hooks, and sign-in / sign-up UI — into your own codebase, so you can edit and theme freely.