Cloudflare Workers

This guide walks you through creating a complete authentication flow using Aura Auth with Cloudflare Workers.

Overview

Cloudflare Workers use the Fetch API (Request and Response), which matches Aura Auth's framework-agnostic design. That makes the integration simple: you can mount Aura Auth directly in the worker fetch handler and keep your auth logic in one shared module.

Before continuing, complete the installation and initial setup:

Quick Start Guide to create your Aura Auth instance
TypeScript Configuration for TypeScript-specific setup
Cloudflare Integration App for a fully working example

Then use this guide to integrate Aura Auth with a Cloudflare Worker using best practices.

What You'll Build

You will create a small Cloudflare Worker app with:

a shared src/lib/auth.ts server configuration
a src/index.ts worker entry point that mounts the auth handlers
Cloudflare secret bindings for auth credentials
a worker example that routes auth requests and returns 404 for everything else

Project Structure

auth.ts

index.ts

.env.local

wrangler.jsonc

Environment Setup

Create a .env.local file at the root of your project to store secrets securely.

.env.local

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

Never commit your .env.local file to version control. Use a secret manager in production.

Using the wrangler CLI or the Cloudflare dashboard, add the required secret environment variables. Workers read secrets from the env argument rather than process.env.

Cloudflare Workers also support secret bindings in the dashboard, which is the preferred option for production deployments.

npx wrangler secret put AURA_AUTH_SECRET
npx wrangler secret put AURA_AUTH_SALT
npx wrangler secret put AURA_AUTH_GITHUB_CLIENT_ID
npx wrangler secret put AURA_AUTH_GITHUB_CLIENT_SECRET

As a second option, you can define the variables locally in a .env file and generate the Env type with the wrangler CLI:

wrangler types

Setup Aura Auth

Set up your auth.ts file in src/lib/ and configure Aura Auth for your Cloudflare Worker.

src/lib/auth.ts

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

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

export const { handlers, jose, api } = auth

basePath must match the route you expose in your worker. If the route changes, update the auth config and handler together.

Mount HTTP Handlers

Because Workers pass environment variables into the fetch execution context, keep your auth setup in a separate module and route /api/auth/* requests to handlers.ALL.

The worker below delegates only auth requests to Aura Auth and returns a 404 for everything else.

src/index.ts

import { handlers } from "./lib/auth"

export default {
  async fetch(request: Request): Promise<Response> {
    const pathname = new URL(request.url).pathname
    if (pathname.startsWith("/api/auth/")) {
      return await handlers.ALL(request)
    }
    return new Response("Not Found", { status: 404 })
  },
} satisfies ExportedHandler<Env>

Use this pattern when you want a single worker to handle both auth endpoints and a small number of custom routes.

Common Pitfalls

Keep basePath aligned with the worker route. If your auth endpoint is /api/auth/*, the auth config should use basePath: "/api/auth".
Use Cloudflare secret bindings in production. Workers should read credentials from env, not from process.env.
Keep the auth logic in one module. Import src/lib/auth.ts from your worker entry point so the handlers stay shared and consistent.
Return a 404 for non-auth routes. That keeps the worker behavior explicit and easier to debug.