Quick Start

Installation

Install the package. Using pnpm is recommended for monorepos due to improved speed and disk efficiency, but npm and yarn work as well.

npm install @aura-stack/auth

Environment setup

Store secrets and provider credentials in environment variables. Aura Auth follows this naming convention:

• AURA_AUTH_SECRET Required opaque value used to sign and encrypt sessions/csrf tokens
• AURA_AUTH_SALT: Required random salt used for derivation keys for signing and encryption.
• AURA_AUTH_{PROVIDER}_CLIENT_ID
• AURA_AUTH_{PROVIDER}_CLIENT_SECRET

Create a .env file (do not commit it):

# 32-byte (256-bit) secret used to sign and encrypt sessions. Use a secure random value.
AURA_AUTH_SECRET="base64-or-hex-32-bytes"
AURA_AUTH_SALT="base64-or-hex-32-bytes"

# GitHub OAuth credentials
AURA_AUTH_GITHUB_CLIENT_ID=your_github_client_id
AURA_AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret

Create an Auth instance

The createAuth function is used to create the Aura Auth instance configuration. This defines the OAuth Providers to be consumed, Cookie Management, Trusted Origins, Session management and other settings to control the library's behavior and flows.

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

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

The createAuth function returns an Aura Auth instance, which includes HTTP handlers for authentication flows, jose utilities for token signing and verification, and api methods to interact with the auth flows (programmatically trigger sign-in, sign-out, get session, etc.).

Client-side

Once the Aura Instance is configured, HTTP handlers (GET, POST) are available for integration into routers or frameworks.

The returned handlers include pre-built routes used in OAuth flows (/signIn/:oauth, /callback/:oauth, /session, /signOut, and /csrfToken). These can be mounted in Express, Hono, Next.js, or any runtime that supports native Request and Response APIs.

import { auth } from "@/auth"

export const {
  handlers: { GET, POST },
} = auth

Now integrate the handlers into your framework or router.

Interact with API methods

The Aura Auth instance also provides API methods to interact with the authentication flows programmatically. For example, you can trigger a sign-in flow, get the current session, or sign out a user.

import { auth } from "@/auth"

const signIn = await auth.api.signIn("github", {
  redirectTo: "https://yourapp.com/dashboard",
})

const session = await auth.api.getSession({
  headers: request.headers,
})

const signOut = await auth.api.signOut({
  headers: request.headers,
  redirectTo: "https://yourapp.com",
})

const updateSession = await auth.api.updateSession({
  headers: request.headers,
  session: {
    user: {
      name: "John Doe",
      email: "johndoe@example.com",
    },
  },
})

Interact with Client API

The Aura Auth instance also provides a client API for use in frontend applications. This allows you to trigger sign-in flows, get the current session, and sign out users directly from the client side.

import { createAuthClient } from "@aura-stack/auth/client"

export const authClient = createAuthClient({
  baseURL: "http://localhost:3000",
  basePath: "/api/auth",
})

const signIn = await authClient.signIn("github", {
  redirectTo: "https://yourapp.com/dashboard",
})

const signOut = await authClient.signOut({
  redirectTo: "https://yourapp.com",
})

const session = await authClient.getSession()

const updatedSession = await authClient.updateSession({
  user: {
    name: "John Doe",
    email: "johndoe@example.com",
  },
})

Next Steps

Aura Auth is framework-agnostic. To use it in a real application, it must be integrated into a server runtime.

Choose your integration based on your stack:

• Astro
• Bun
• Cloudflare Workers
• Deno
• Elysia
• Express
• Hono
• Next.js
• Nuxt.js
• Oak
• React Router
• Supabase Edge Functions
• TanStack Start
• Vercel Edge Functions