Configuration

The core of gau is the createAuth function, which you use to configure your auth setup. This guide covers all the available options in detail.

Here’s a quick overview of a typical configuration:

auth.ts

import { DrizzleAdapter } from '@rttnd/gau/adapters/drizzle';
import { createAuth } from '@rttnd/gau/core';
import { GitHub } from '@rttnd/gau/oauth';
import { db } from './db';
import { Accounts, Users } from './db/schema';

export const auth = createAuth({
  adapter: DrizzleAdapter(db, Users, Accounts),
  providers: [
    GitHub({
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    }),
  ],
  jwt: {
    secret: process.env.AUTH_SECRET,
  },
});

adapter

Type: Adapter, Required: Yes

The adapter is responsible for connecting gau to your database and handling db operations.

See the adapters guide.

providers

Type: OAuthProvider[], Required: Yes

This option takes an array of configured OAuth providers that your application will support.

Each provider typically needs a clientId and clientSecret.

import { GitHub, Google } from '@rttnd/gau/oauth';

// ...
providers: [
  GitHub({
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  }),
  Google({
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  }),
],

Check out the OAuth Providers section for a list of available providers and their specific configuration.

basePath

Type: string, Default: '/api/auth'

Defines the relative path for all authentication API endpoints. You typically don’t need to change this.

The resulting URL is {baseURL}/{basePath}/{provider}.

If your frontend and backend are on different hosts, look for the baseURL config in the framework specific guides.

session

Type: object, Default: {}

This object allows you to configure session management.

session.strategy

Type: 'auto' | 'cookie' | 'token', Default: 'auto'

Determines how sessions are handled. See the Session Management guide for a detailed explanation of the different strategies.

• 'auto' (Default): Automatically switches between cookie and token strategies based on the redirect URL.
• 'cookie': Always use cookies.
• 'token': Always use tokens passed in the URL.

jwt

Type: object, Default: {}

This object allows you to configure JSON Web Token settings for session management.

jwt.secret

Type: string, Required: Yes

The secret used for signing and verifying JWTs.

For HS256, this can be a simple string. For the default and recommended ES256, this must be a base64url-encoded PKCS#8 private key. You can generate a valid secret using the CLI:

npm

npx gau secret

pnpm

pnpm dlx gau secret

yarn

yarn dlx gau secret

bun

bunx gau secret

ni

nlx gau secret

jwt.algorithm

Type: 'ES256' | 'HS256', Default: 'ES256'

The signing algorithm to use.

ES256 (ECDSA with P-256 and SHA-256) is the default and recommended algorithm. It uses asymmetric cryptography (a private key to sign, a public key to verify), which is generally more secure than symmetric algorithms like HS256. HS256 is for backend-only setups, and it’s a bit faster.

jwt.privateKey

Type: CryptoKey, Required: No

The private key to use for signing JWTs, only with ES256.

By default, this is derived from jwt.secret.

jwt.ttl

Type: number, Default: 86400 (24 hours)

The default time-to-live for session JWTs, in seconds.

jwt.iss, jwt.aud, and jwt.sub

Type: string | string[]

Standard JWT claims for “issuer” (iss) and “audience” (aud). These are useful in multi-tenant applications or when your API needs to serve different clients. gau allows you to set default values for them here, and will automatically validate these claims when verifying a token.

cookies

Type: cookie.SerializeOptions, Default: { path: '/', sameSite: 'lax', secure: true, httpOnly: true }

Allows you to customize the options for the session cookie.

You can override the defaults. For example:

cookies: {
  sameSite: 'strict',
},

trustHosts

Type: 'all' | string[], Default: []

For CSRF protection. It defines which hosts are allowed to make POST requests to your auth endpoints.

The Origin header of incoming requests is checked against this list.

• [] (Default): Only requests from the same origin as the app are allowed.
• ['tauri.localhost']: For Tauri apps, you should add tauri.localhost.
• 'all': This is a convenient shortcut for development, not recommended for production.

See the Security guide for more details.

autoLink

Type: 'verifiedEmail' | 'always' | false, Default: 'verifiedEmail'

Controls how gau does automatic account linking.

Read the Account Linking guide for a full explanation.

• 'verifiedEmail' (Default): If an existing user signs in with a new OAuth provider, gau will try very hard to get a verified email address from the provider, then it will automatically link the new account to that existing user. Otherwise, it will create a new user.
• 'always': Links accounts if the email addresses match, regardless of whether the email is verified by the provider.
• false: Disables automatic account linking. A new user will be created for each new OAuth provider sign-in, even if the email already exists.