Browser-side helpers for AuthGate (logout, CSRF forwarding)
npm install @authgate/browserMinimal browser-side helpers for applications using AuthGate.
This package provides explicit, framework-agnostic primitives for integrating
browser-based UIs (SSR or SPA) with an AuthGate-backed authentication system.
It intentionally avoids hidden behavior, background state mutation, or
framework-specific abstractions.
---
- Explicit behavior (no magic, no background auth)
- Browser-only responsibility (cookies, CSRF, refresh)
- Framework-agnostic (React, Vue, Svelte, vanilla JS)
- Composable primitives + optional convenience helpers
- Zero dependencies
---
- Read AuthGate CSRF token from browser cookies
- Perform a CSRF-protected logout request
- Explicit browser-side session refresh with audience selection
- Optional fetch wrapper with single-retry refresh semantics
- Clear success / failure signaling
- Optional redirect on logout
- No runtime dependencies
---
``bash`
npm install @authgate/browser
---
`ts
import { getCSRFToken } from "@authgate/browser";
const csrf = getCSRFToken();
`
Returns the value of the authgate_csrf cookie, or null if not present.
This function only reads the CSRF token.
It does not generate or validate it.
---
`ts
import { logout } from "@authgate/browser";
const result = await logout();
`
This will:
- Send a POST /auth/logout requestX-CSRF-Token
- Attach the CSRF token via
- Include credentials ()
The function returns an explicit result:
`ts`
type LogoutResult =
| { ok: true }
| { ok: false; reason: "missing_csrf" | "request_failed" | "unauthorized" };
Applications that do not need to react programmatically may safely ignore the
return value.
---
`ts`
await logout({ redirectTo: "/" });
If the logout request succeeds, the browser is redirected to the given path.
Redirecting is an optional side-effect and does not define success.
---
`ts
import { refreshSession } from "@authgate/browser";
const refreshed = await refreshSession("app");
`
Attempts to refresh the current AuthGate session by calling:
`text`
POST /auth/refresh
with an explicit audience declaration.
The audience determines which access token is minted (e.g. "app", "admin").
- The client explicitly requests an audience
- AuthGate validates the requested audience against the user’s roles
- Requests for unauthorized audiences fail with 401
If no audience is provided, "app" is used by default.
- Returns true if refresh succeededfalse
- Returns if refresh failed for any reason
This function:
- does not retry
- does not redirect
- does not throw
- does not modify application state
It is intended for applications that want manual control over refresh logic.
---
`ts
import { authFetch } from "@authgate/browser";
const res = await authFetch("/api/data");
`
authFetch is an optional convenience wrapper around fetch with
AuthGate-aware refresh behavior.
1. Performs the request with credentials
2. If the response is not 401, returns it directly
3. If the response is 401:
- Attempts refreshSession() with the same audience401
- If refresh succeeds, retries the original request once
- Otherwise, returns the original response
`ts`
await authFetch("/admin/api/users", {}, { audience: "admin" });
- The same audience is used for the refresh attempt
- Unauthorized audiences fail cleanly without retry loops
- At most one retry
- No redirects
- No background refresh
- No swallowed failures
Applications remain fully in control of UX decisions.
---
`ts
const res = await authFetch("/api/me");
if (res.status === 401) {
setUser(null);
}
`
Admin request:
`ts``
const res = await authFetch(
"/admin/api/users",
{},
{ audience: "admin" },
);
---
- CSRF tokens are not generated by this package
- CSRF validation is enforced by AuthGate
- Refresh tokens are never exposed to JavaScript
- All authentication state is owned by AuthGate
- Audiences are explicitly requested and server-validated
This package only forwards existing browser state explicitly.
---
- No authentication logic
- No credential storage
- No background token refresh
- No session management
- No authorization or role handling
- No implicit redirects
- No framework-specific helpers
This package exists solely to reduce boilerplate and prevent integration mistakes
while preserving full application control.
---
- Works with any backend protected by AuthGate
- Supports SSR, SPA, and hybrid architectures
---