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_{PROVIDER}_CLIENT_ID
• AURA_AUTH_{PROVIDER}_CLIENT_SECRET
• AURA_AUTH_SECRET (used to sign and encrypt sessions/csrf tokens)

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"

# 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 configuration options, and other settings to control the library's behavior and flows.

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

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

Get HTTP Handlers

Once the Aura Instance is configured, HTTP handlers (GET and 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 { createAuth } from "@aura-stack/auth"

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

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

These handlers internally provide:

The usage of the HTTP handlers depends of the library and frameworks integration, just, Aura Auth provides the endpoint for the OAuth 2.0 flows which includes:

Set up HTTP Handlers

Now integrate the handlers into your framework or router.