Authdog
Developers guide

Framework SDKs

Authdog framework SDKs connect browser or framework lifecycle events to Authdog identity, but their security properties differ by package and runtime. Client identity state supports rendering and navigation. Trusted server validation protects data and state-changing operations. A token-shaped string, browser storage entry, cookie-presence flag, client route guard, or rendered user is not equivalent to server-validated authentication.

Prerequisites

  • An Authdog environment and its publishable pk_... public key.
  • A supported framework package selected from the repository’s SDK catalog.
  • A callback URL configured for the same environment.
  • A trusted backend path for every protected operation.
  • An authorization policy applied after authentication.

Repository documentation lists frontend integrations for Next.js, React Elements, Remix, React Native/Expo, SvelteKit, TanStack Start, Vue, Angular, Astro, Gatsby, and RedwoodJS. React Elements is presentational only; use it for UI, not session integration.

Before implementation, read the selected framework page. Packages do not expose one uniform security boundary. Some include userinfo-backed server helpers; some only bootstrap a browser token; some read cookies without validating them.

Implementation

Separate integration into two layers.

Client identity layer: receives callback state, removes sensitive query parameters, fetches profile data where supported, and shapes UI. This layer can decide what to display, where to navigate, or whether to prompt for sign-in. It cannot protect an API from a caller that bypasses the browser.

Trusted server layer: reads a cookie or bearer token, validates it through the package’s documented server mechanism, rejects unauthenticated requests, and applies authorization. This layer owns protected Route Handlers, loaders, actions, functions, API routes, and backend services.

For Next.js App Router, @authdog/nextjs-app exports a client AuthdogProvider, useUser, and useAuth. The provider stores a callback value only when it has three JWT-shaped segments. That is a shape check, not signature, issuer, audience, or expiry validation. useUser calls userinfo; useAuth only reports whether a browser token exists.

On the server, useAuthMiddleware(publicKey) validates the callback through Authdog userinfo and writes HttpOnly cookies:

import { useAuthMiddleware } from "@authdog/nextjs-app/server"

export default useAuthMiddleware(process.env.PK_AUTHDOG!)

This middleware handles callback exchange. Repository documentation explicitly says it does not protect routes or validate cookies on later requests. Protected Route Handlers and Server Actions still need independent credential validation on every request.

For Remix, identityLoader() validates callback and cookie credentials through userinfo and returns { user, isAuthenticated, signinUri }. The result does not redirect or deny access automatically. Check isAuthenticated in each protected loader. Preserve the loader’s original Response headers when processing a callback, or its Set-Cookie headers are lost.

Other packages require similarly specific handling:

  • Angular’s route guard is a UX convenience. Its browser token shape check is not cryptographic validation.
  • Expo’s deep-link handler checks JWT structure before storage; the backend must validate the bearer token.
  • SvelteKit’s locals.authdog.isAuthenticated means a cookie exists. Use getUser(request) for userinfo-backed validation.
  • Vue’s current server getSession() result is untrusted raw session input; repository docs state its server helper has no validating getUser method.
  • Gatsby and Redwood provide server requireAuth gates that validate through userinfo.
  • Astro documents createAuthdogServer().getUser() as the validating server decision.

Security considerations

Expose only the publishable public key to client code. Keep confidential client credentials and any backend secrets server-side.

Treat callback tokens carefully. Remove them from URLs after processing, but never confuse removal or three-segment matching with verification. If a package stores tokens in local storage, assume browser script can access them and validate every API request independently.

Cookie presence is not token validity. A trusted server must validate before granting access. Where callback exchange sets cookies, preserve security attributes documented by the integration, including HttpOnly, Secure, and SameSite where applicable.

Authentication and authorization remain separate. A validated user or service identity still needs role, permission, organization, tenant, or resource checks for the requested operation.

Complete logout may require clearing both browser storage and server cookies. Follow package-specific helpers; clearing a React state value alone does not terminate server access.

Validation checklist

  • Client and server use configuration for the same Authdog environment.
  • Callback URL is handled by the intended framework route.
  • Callback token is validated before a trusted cookie is created.
  • Query token is removed after processing.
  • Protected server operation validates credentials on every request.
  • Browser route guards and identity hooks are treated as UX only.
  • Authorization runs after successful authentication.
  • Callback Set-Cookie headers survive framework response adaptation.
  • Logout clears every storage location used by the selected SDK.
  • Development credentials and sessions do not cross into production.

Troubleshooting

If UI reports authenticated but an API returns 401, inspect whether client state only proves token presence. Confirm the server receives the cookie or bearer header and uses a validating helper.

If callback succeeds but later requests are anonymous, verify that the callback route returned all Set-Cookie headers and that cookie scope and security attributes match the deployment.

If server code sees a cookie yet grants should fail, check the package guide: some middleware only records cookie presence. Replace presence checks with the documented userinfo-backed method or backend SDK.

If logout appears incomplete, identify whether the package uses local storage, server cookies, or both, then invoke each documented cleanup path.

Next steps