{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udd10 react-auth \u2014 Authentication UI and State","text":"

react-auth is the front-end half of the Aetos auth story: a JWT-backed AuthProvider, a pluggable login/register screen, profile screens, and an axios factory that carries bearer tokens and reacts to 401 responses. The server side lives in the Auth Server service; this package never defines an endpoint contract of its own.

Doc model: this wiki is written for humans \u2014 guides and wiring recipes. The authoritative API contracts live in the code (RDFC JSDoc) and the machine-readable bundle under docs/mcp/. Browse the TypeDoc site for the full symbol reference.

"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":""},{"location":"#documentation-structure","title":"\ud83d\udce6 Documentation Structure","text":"Section Description Overview What the library is, and the token/session lifecycle Wiring Guide Drop-in recipes for provider, gate and profile flows"},{"location":"#quick-start","title":"\ud83d\ude80 Quick Start","text":"
import { AuthProvider, useAuth, AuthPage } from \"react-auth\";\n\nexport default function Root() {\n  return (\n    <AuthProvider\n      authConfig={{\n        serverUrl: \"https://api.example.com\",\n        loginPath: \"/auth/login\",\n        registerPath: \"/auth/register\",\n        logoutPath: \"/auth/logout\",\n        mePath: \"/auth/me\",\n        introspectPath: \"/auth/introspect\",\n      }}\n    >\n      <LoginGate />\n    </AuthProvider>\n  );\n}\n
"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"

\u00a9 Aetoskia Internal \u2014 react-auth 0.0.1

"},{"location":"01_overview/","title":"Library Overview","text":"

react-auth owns three concerns and nothing else: session state, the authenticated HTTP client, and the screens that produce a session. It talks to an auth server over HTTP \u2014 it never issues, validates or decodes tokens itself.

"},{"location":"01_overview/#what-lives-where","title":"\ud83e\udded What lives where","text":"Concern Module Notes Session state contexts.tsx AuthProvider, useAuth, AuthServerConfig Authenticated HTTP client axios.ts createApiClient, attachAuthInterceptors Token persistence token.ts tokenStore (localStorage, key \"token\") Login / register screen AuthPage.tsx AuthPage, AuthMode Profile screens Profile*.tsx controlled presentational components User model models.ts AuthUser

The package entry (index.ts) re-exports the public surface; nothing else in the app should import the internals directly.

"},{"location":"01_overview/#session-lifecycle","title":"\ud83d\udd04 Session lifecycle","text":"
  1. Bootstrap \u2014 AuthProvider seeds its token from tokenStore.get().
  2. Resolve the user \u2014 whenever the token changes, mePath is fetched and currentUser is set (or cleared).
  3. Login \u2014 login(username, password) posts to loginPath, stores access_token through tokenStore, and takes currentUser from the response user.
  4. Register \u2014 register(...) creates the account, then logs in.
  5. Request \u2014 every client built by createApiClient attaches Authorization: Bearer <token> from tokenStore.
  6. Expiry \u2014 a 401 clears the token and dispatches an auth:unauthorized window event; AuthProvider listens, clears the session, and invokes the optional onUnauthorized callback.
  7. Logout \u2014 best-effort call to logoutPath, then local state is always cleared.

One source of truth

tokenStore is the only place the token is written. Reading it from anywhere else will desynchronise the UI from the network layer.

"},{"location":"01_overview/#endpoint-contract","title":"\ud83c\udfd7\ufe0f Endpoint contract","text":"

AuthServerConfig is the complete wiring surface; every path resolves relative to serverUrl:

Field Shape loginPath POST { username, password } \u2192 { access_token, user } registerPath POST { username, password } to create an account logoutPath called on logout; failures are ignored mePath returns the current AuthUser for a valid bearer token introspectPath token introspection, available to callers that need it

AuthUser is intentionally permissive so it can be spread into application state without loss.

"},{"location":"01_overview/#read-next","title":"\u27a1\ufe0f Read Next","text":""},{"location":"02_wiring/","title":"Wiring Guide","text":"

Recipes for the three things every Khata front-end does: mount the provider, gate on the session, and edit the profile. All of these are presentational \u2014 swap in your own router or layout as needed.

"},{"location":"02_wiring/#1-mount-the-provider","title":"\ud83d\udce6 1. Mount the provider","text":"
import { AuthProvider } from \"react-auth\";\nimport type { AuthServerConfig } from \"react-auth\";\n\nconst authConfig: AuthServerConfig = {\n  serverUrl: \"https://api.example.com\",\n  loginPath: \"/auth/login\",\n  registerPath: \"/auth/register\",\n  logoutPath: \"/auth/logout\",\n  mePath: \"/auth/me\",\n  introspectPath: \"/auth/introspect\",\n};\n\nexport default function Root() {\n  return (\n    <AuthProvider authConfig={authConfig} onUnauthorized={() => console.info(\"session expired\")}>\n      <App />\n    </AuthProvider>\n  );\n}\n

AuthProvider must wrap any component that calls useAuth.

"},{"location":"02_wiring/#2-gate-on-the-session","title":"\ud83d\udce6 2. Gate on the session","text":"
import { useAuth, AuthPage } from \"react-auth\";\nimport { useState } from \"react\";\n\nfunction LoginGate({ children }: { children: React.ReactNode }) {\n  const auth = useAuth();\n  const [mode, setMode] = useState<\"login\" | \"register\">(\"login\");\n\n  if (auth.currentUser) return <>{children}</>;\n\n  return (\n    <AuthPage\n      mode={mode}\n      onBack={() => history.back()}\n      onSwitchMode={() => setMode((m) => (m === \"login\" ? \"register\" : \"login\"))}\n      login={auth.login}\n      register={auth.register}\n      loading={auth.loading}\n      error={auth.error}\n      currentUser={auth.currentUser}\n    />\n  );\n}\n

Automatic redirect

AuthPage calls onBack on its own once currentUser becomes truthy, so it works as a route guard without a useEffect. mode is fully controlled, so the login/register toggle never unmounts the form.

"},{"location":"02_wiring/#3-profile-screens","title":"\ud83d\udce6 3. Profile screens","text":"

ProfileCreate, ProfileEdit and ProfileView render the profile UI and delegate persistence to callbacks you supply \u2014 the library does not know how your backend stores profiles.

The three screens take flat props, not a user object:

Component Props ProfileView name, username, email, onEdit?, loading? ProfileEdit name, username, email, onSubmit, onBack?, loading?, error? ProfileCreate onSubmit, defaultUsername?, defaultEmail?, onBack?, loading?, error? 
import { ProfileView, ProfileEdit, useAuth } from \"react-auth\";\nimport { useState } from \"react\";\n\nfunction ProfileRoute() {\n  const { currentUser } = useAuth();\n  const [editing, setEditing] = useState(false);\n\n  if (!currentUser) return null;\n  const { username, email } = currentUser;\n  const props = { username, email, name: username };\n\n  if (editing) {\n    return <ProfileEdit {...props} onBack={() => setEditing(false)} onSubmit={saveProfile} />;\n  }\n  return <ProfileView {...props} onEdit={() => setEditing(true)} />;\n}\n

onSubmit always receives { name, email } \u2014 persistence is yours.

Client-side validation only

AuthPage validates username >= 3 and password >= 6 before calling your callback. The auth server remains the authority \u2014 never skip its validation.

"},{"location":"02_wiring/#4-authenticated-api-calls","title":"\ud83d\udce6 4. Authenticated API calls","text":"
import { createApiClient } from \"react-auth\";\n\nconst api = createApiClient(\"https://api.example.com\");\nconst { data } = await api.get(\"/expenses\"); // Authorization added automatically\n

Use createApiClient for any backend that shares the auth-server login. A plain axios instance is fine for unauthenticated endpoints.

For an existing client, attachAuthInterceptors(client) decorates it in place with the same request/response behaviour.

"},{"location":"02_wiring/#related","title":"\ud83d\udd17 Related","text":""}]}