← Integration Docs

Framework integration guides

Choose your registered client type in App → API Keys. These are integration recipes for Auth’s hosted web and public native protocols, not dedicated framework adapters. Copying configuration does not implement a callback, create a session or verify a connection. No live sign-in or framework runtime is tested by this guide.

Shared hosted web contract

  1. Register a Web app and save the exact callback in the intended active environment. Select the same environment in API Keys. Configure public app ID, Auth origin and return URL; only your backend receives that environment’s server API key.
  2. Start login from a user action using the code below. Auth displays the app’s enabled and available methods. This generic hosted flow works independently of a front-end framework.
  3. The existing hosted callback returns a token in the URL. Your callback must avoid URL analytics/logging, remove the token from browser history, send it securely to your own backend, and verify it using Auth’s documented server contract before accepting identity. Do not trust client decoding or create a session from an unverified token.
  4. Implement your own protected application session and logout. Use secure HttpOnly cookies where appropriate, protect state-changing endpoints against CSRF and authorize every protected server operation. Auth does not automatically add middleware or protected routes to your app.
  5. Add the connection-test helper and run an authorized real sign-in round trip. An On toggle, copied template or successful redirect alone does not mean Verified.
// Client-side click handler. Read these public values from your framework config.
const url = new URL('/login', authOrigin);
url.searchParams.set('app', appId);
url.searchParams.set('redirect_uri', registeredCallback);
window.location.assign(url.toString());
Server verification examples and hosted session boundaries →

Next.js

Hosted web flow. Start sign-in in a client event handler; verify the callback on your server before creating your app session.

  1. Copy NEXT_PUBLIC_AELITH_* values into your app configuration. Read them in a Client Component click handler; keep AELITH_API_KEY in server-only code.
  2. Create your registered callback page and a server Route Handler to verify the returned token. Set your application’s session only after successful verification.
  3. Protect each server data/action entry point. A client layout redirect alone is not authorization.

Follow the shared hosted contract for callback validation, server verification, session creation and testing.

React · Vite

Hosted web flow. Vite configuration is public; use a separate backend for verification and session creation.

  1. Use VITE_AELITH_* values through import.meta.env. Vite bundles these into public client code; never add a key to them.
  2. Create a callback route in your chosen router and invoke the shared login code from a component click handler. Configure the web host to serve the callback route on direct navigation.
  3. A static Vite deployment needs a separate backend for Auth verification, session creation and protected API authorization. AELITH_API_KEY belongs there.

Follow the shared hosted contract for callback validation, server verification, session creation and testing.

React Router

Hosted web flow. Use a callback route and server verification. SPA mode needs a separate backend; protect every data loader/action.

  1. This template assumes a Vite-based React Router app: read public VITE_AELITH_* values in client code. For another build tool, map the same public values using its supported configuration.
  2. Add a callback route. Framework/SSR mode can use a server action or endpoint for verification/session creation; SPA/static mode needs a separate backend. Keep AELITH_API_KEY server-only and never return it from a loader.
  3. Authorize every protected loader/action or supported server middleware. Parent route checks alone do not guard all parallel data requests. No Aelith React Router adapter or automatic route guard is provided.

Follow the shared hosted contract for callback validation, server verification, session creation and testing.

Nuxt

Hosted web flow. Declare runtimeConfig public values separately from the private server API key; verify callbacks in a server route.

// nuxt.config.ts — declare keys so NUXT_* overrides apply.
export default defineNuxtConfig({
  runtimeConfig: {
    aelithApiKey: '', // NUXT_AELITH_API_KEY: server only
    public: {
      aelithAppId: '', // NUXT_PUBLIC_AELITH_APP_ID
      aelithAuthOrigin: '', // NUXT_PUBLIC_AELITH_AUTH_ORIGIN
      aelithRedirectUri: '', // NUXT_PUBLIC_AELITH_REDIRECT_URI
    },
  },
});
  1. Copy NUXT_PUBLIC_AELITH_* and private NUXT_AELITH_API_KEY values into your deployment’s configuration. Declare matching runtimeConfig keys above. Public values are serialized to the client.
  2. In the client click handler read useRuntimeConfig().public and map aelithAppId, aelithAuthOrigin and aelithRedirectUri to the shared hosted code. Add a callback page matching the registered URL.
  3. In a Nuxt server route use useRuntimeConfig(event).aelithApiKey for backend verification, then establish your own secure session. Do not return the private config from that route. Static generation still requires a separate backend.

Follow the shared hosted contract for callback validation, server verification, session creation and testing.

Vue · Vite

Hosted web flow. Add a Vue Router callback and a backend session endpoint. Never place the server key in Vite configuration.

  1. Use VITE_AELITH_* values through import.meta.env. Vite bundles these into public client code; never add a key to them.
  2. Create a Vue Router callback route and invoke the shared login code from a component click handler. Configure the web host to serve the callback route on direct navigation.
  3. A static Vite deployment needs a separate backend for Auth verification, session creation and protected API authorization. AELITH_API_KEY belongs there.

Follow the shared hosted contract for callback validation, server verification, session creation and testing.

JavaScript · web

Hosted web flow. Implement the callback and backend verification; browser code cannot securely hold a server key.

  1. Map the template’s public AELITH_APP_ID, AELITH_AUTH_ORIGIN and AELITH_REDIRECT_URI into your application’s browser configuration; these example names are not automatically read by a library.
  2. Serve your exact callback path and implement the shared hosted contract. Keep AELITH_API_KEY only in your separate backend, not a script tag, JSON config or browser storage.

Follow the shared hosted contract for callback validation, server verification, session creation and testing.

Shared public native contract

Register Mobile App, not a confidential web client. Retain a fresh verifier, S256 challenge, state and nonce per attempt. Start /api/oauth/authorize with client_id, redirect_uri, response_type=code, code_challenge, code_challenge_method=S256, state, nonce and an enabled supported provider. Validate the exact return URL and state; exchange the one-time code via form-encoded POST /api/oauth/token with grant_type=authorization_code, client_id, redirect_uri, code and code_verifier. Never include a client secret or server API key.

Validate the resulting session and keep accepted tokens in platform secure storage, not ordinary browser or unencrypted app storage. Handle cancellation, app return, failed exchanges, expiry and revocation; discard attempt secrets after completion/cancellation and never reuse a verifier. Refresh tokens are conditional on server/app configuration; handle reauthentication when refresh is unavailable. Fetch current method capabilities rather than hardcoding all providers. Native GitHub is not implemented; direct native passkey sheets are not supplied.

Exact native protocol, session and credential-flow guide →

iOS · Swift

Public native S256 PKCE flow. Register the URL handler and use secure token storage; direct Apple/email UI requires additional native credential integration.

  1. Configure the app target’s return URL handler. Use ASWebAuthenticationSession for browser PKCE; Keychain for accepted session tokens. The native Apple sheet requires its separate capability, audience and credential exchange.
  2. Implement the shared native contract and integrate the source session helper if suitable. Wire cancellation, secure storage, session validation and reauthentication in your application.

Expo

Protocol integration with Expo AuthSession, not a dedicated Aelith Expo SDK. Requires a development build, exact return URL, S256 PKCE and secure session storage.

  1. Configure your own reverse-domain scheme in app.json/app.config, build a development or standalone app, and register the complete return URL in Auth. Expo Go cannot supply the required custom scheme. A scheme change requires a native rebuild.
  2. Install compatible expo-auth-session and expo-crypto with expo install, plus the secure-storage/browser modules your app uses. EXPO_PUBLIC_AELITH_* values are public; reference them with static process.env.EXPO_PUBLIC_* property access and map them explicitly to your request.
  3. Use AuthSession.makeRedirectUri with your configured scheme/path. Compare its actual output with the exact Auth registration; do not assume slash/host variants are equivalent.
  4. Build useAuthRequest with responseType code, usePKCE true, CodeChallengeMethod.S256, clientId, exact redirectUri, fresh state and extraParams containing provider and nonce. Use Auth’s authorization/token endpoints from the shared native contract. Wait for request readiness and invoke promptAsync only on a user action.
  5. On success validate return/state and consume the original request once. Redeem using exchangeCodeAsync with clientId, redirectUri, code and extraParams.code_verifier=request.codeVerifier; never supply a clientSecret. Validate/store the accepted session, clear attempt state, and implement cancel/retry/expiry/revocation handling. This browser PKCE recipe does not implement a native Apple sheet or in-app email form.

JavaScript · native PKCE

Public native S256 PKCE flow. Supply a system-browser adapter, secure randomness and platform secure storage; browser JavaScript alone is not a native integration.

  1. Supply the native runtime’s system authentication browser and registered return handler. A generic JavaScript config object alone cannot receive native deep links.
  2. Implement the shared native contract and integrate the source session helper if suitable. Wire cancellation, secure storage, session validation and reauthentication in your application.

Framework references and test boundaries

These recipes are checked against Auth’s source contract and local configuration tests, not a live Expo device or every framework runtime. Source helper downloads are not a claim of a separately published framework SDK. Complete integration and a real authorized connection test remain required.