Configuration Options

createAuth configuration options

basePath

Base path prefix where Aura Auth endpoints are mounted and exposed to your routing system. Defaults to /auth.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  basePath: "/auth",
})

cookies

Per-cookie configuration to override Aura Auth's defaults. You can set a cookie name prefix and adjust the cookies Aura Auth uses internally. See API Reference for details.

Supported cookies: sessionToken, csrfToken, state, codeVerifier, redirectTo, and redirectURI. Set per-cookie attributes as needed. For autocomplete and safer suggestions, set the strategy field, which provides type-safe defaults that follow cookie best practices.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  cookies: {
    prefix: "aura-auth",
    overrides: {
      sessionToken: {
        name: "session_token",
        attributes: {},
      },
    },
  },
})

oauth

Configures OAuth providers for an auth instance. Aura Auth's built-in providers can be used, or custom providers supplied.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
})

Built-in OAuth Providers

Aura Auth ships ready-to-use OAuth providers. The oauth option in createAuth autocompletes these provider IDs (names are lowercase).

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: ["github"],
})

Custom OAuth Providers

Provider configs are available via @aura-stack/auth/oauth/index (all providers) or @aura-stack/auth/oauth/:provider (specific). See OAuth Providers for details. Custom providers must implement OAuthProvider.

import { createAuth, type OAuthProvider } from "@aura-stack/auth"
import { github } from "@aura-stack/auth/oauth/index"

export const auth = createAuth({
  oauth: [
    {
      ...github,
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    } as OAuthProvider,
  ],
})

or

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [
    {
      id: "github",
      name: "GitHub",
      authorizeURL: "https://github.com/login/oauth/authorize",
      accessToken: "https://github.com/login/oauth/access_token",
      userInfo: "https://api.github.com/user",
      scope: "read:user user:email",
      responseType: "code",
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  ],
})

secret

Secret used to sign, encrypt, and hash JWTs, CSRF tokens, and other sensitive values.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  secret: "secret-key",
})

AURA_AUTH_SECRETorAUTH_SECRET environment variables are loaded automatically. If neither is set, an error is thrown during Auth initialization.

To generate a secret value:

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Using OpenSSL
openssl rand -base64 32

trustedProxyHeaders

Enables Aura Auth to read proxy headers when an application runs behind reverse proxies, load balancers, or CDNs to detect the original client protocol and IP.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedProxyHeaders: true,
})

When to Enable: reverse proxy (Nginx, Apache); platforms with automatic proxying (Vercel, Netlify, Heroku); load balancer (AWS ALB, Google Cloud LB); CDN (Cloudflare)

When NOT to Enable: localhost or direct internet connection; untrusted or misconfigured proxy; unclear infrastructure setup

trustedOrigins

Defines the allowed origins for CORS and redirect URI validation. It supports static matches and wildcards in subdomains and ports.

Static Matches

Set the static origins accepted by Aura Auth.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: ["http://example.com", "https://app.example.com:3000"],
})

Dynamic Matches

Set the origin dynamically based on the original request.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: (request) => {
    const origin = request.headers.get("origin")
    if (origin && origin.endsWith(".example.com")) {
      return [origin]
    }
    return []
  },
})

Wildcard Patterns

The * wildcard is supported for flexible matching of subdomains and ports. The wildcard can only be used at the start of a subdomain or as an entire port.

Subdomain Wildcards

Trust one level of subdomains under a specific domain.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: ["https://*.example.com"],
})

It matches any origin that starts with https:// and ends with .example.com, allowing for any single subdomain level (e.g., https://app.example.com, https://www.example.com), but not the root domain itself (https://example.com) or multiple subdomain levels (https://sub.app.example.com).

Port Wildcards

Trust any port on a specific domain.

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: [],
  trustedOrigins: ["https://example.com:*"],
})

It matches any port on https://example.com (e.g., https://example.com:3000, https://example.com:3001, https://example.com:8080), but not the domain without a port (https://example.com) or with a different protocol (http://example.com:3000).