Authdog

Developers guide

Framework SDKs

Authdog framework SDKs connect browser or framework lifecycle events to identity, but their security properties differ by package and runtime. Client identity state is for rendering and navigation; trusted server validation is what protects data. This guide separates the two layers and shows what each package actually verifies.

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.

Repository documentation lists 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.

Implementation

Split integration into two layers. The client identity layer receives callback state, strips sensitive query parameters, and shapes UI, it cannot protect an API from a caller that bypasses the browser. The trusted server layer validates a cookie or bearer token through the package's documented server mechanism and applies authorization, it owns every protected route.

For Next.js App Router, @authdog/nextjs-app exports a client AuthdogProvider, useUser, and useAuth. The provider's callback check is shape-only (three JWT-like segments), not signature or expiry validation. On the server, useAuthMiddleware(publicKey) validates the callback through userinfo and writes HttpOnly cookies:

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

export default useAuthMiddleware(process.env.PK_AUTHDOG!)

This middleware handles callback exchange only, it does not protect routes or validate cookies on later requests. Protected Route Handlers and Server Actions still need independent validation.

For Remix, identityLoader() validates callback and cookie credentials through userinfo and returns { user, isAuthenticated, signinUri } without redirecting automatically, check isAuthenticated in each protected loader.

Other packages need similarly specific handling: Angular's route guard and Expo's deep-link check are UX conveniences, not cryptographic validation. SvelteKit's locals.authdog.isAuthenticated means a cookie exists, use getUser(request) for real validation. Vue's getSession() result is untrusted raw input. Gatsby and Redwood provide server requireAuth gates that validate through userinfo. Astro's createAuthdogServer().getUser() is the validating call.

Security considerations

  • Expose only the publishable public key to client code, keep confidential credentials server-side.
  • Remove callback tokens from URLs after processing, but never confuse removal or shape-matching with verification.
  • Cookie presence is not token validity, a trusted server must validate before granting access.
  • Authentication and authorization remain separate, a validated identity still needs role/permission/organization checks.
  • Complete logout may require clearing both browser storage and server cookies, follow package-specific helpers.

Validation checklist

  • Client and server use configuration for the same Authdog environment.
  • Callback token is validated before a trusted cookie is created.
  • Protected server operation validates credentials on every request.
  • Browser route guards and identity hooks are treated as UX only.
  • Authorization runs after successful authentication.
  • Logout clears every storage location used by the selected SDK.

Troubleshooting

UI reports authenticated but an API returns 401: client state only proves token presence, confirm the server receives the cookie/bearer header and uses a validating helper.

Callback succeeds but later requests are anonymous: verify the callback route returned all Set-Cookie headers and that cookie scope matches the deployment.

Server sees a cookie yet grants fail: some middleware only records cookie presence, replace it with the documented userinfo-backed method.

Next steps