Example guide: Setting up authentication

This is a sample documentation page. It demonstrates how to combine prose, steps, code blocks, and callouts into a realistic guide.

Prerequisites

Before you begin, make sure you have:

A running instance of the application (npm run dev)
An API key from the dashboard

Keep your API key secret. Never commit it to version control or expose it in client-side code.

Configure authentication

Install the SDK

Add the authentication SDK to your project:

npm install @example/auth

Initialize the client

Create an auth client with your API key:

auth.ts

import { createAuthClient } from "@example/auth";

const auth = createAuthClient({
  apiKey: process.env.AUTH_API_KEY,
});

Protect a route

Use the middleware to require authentication:

middleware.ts

import { auth } from "./auth";

export async function onRequest(context, next) {
  const session = await auth.getSession(context.request);

  if (!session) {
    return new Response("Unauthorized", { status: 401 });
  }

  return next();
}

Verify it works

After completing the setup, test that authentication is working:

curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:4321/api/protected

A successful response returns your user data:

{
  "user": {
    "id": "usr_123",
    "email": "ada@example.com"
  }
}

Common issues

401 Unauthorized on every request

Check that your AUTH_API_KEY environment variable is set and matches the key in your dashboard.

Session expires immediately

The default session duration is 24 hours. You can extend it in the client configuration:

const auth = createAuthClient({
  apiKey: process.env.AUTH_API_KEY,
  sessionDuration: "7d",
});

Example guide: Setting up authentication

Prerequisites

Configure authentication

Verify it works

Common issues

Next steps

Components

Customization