Next.js Customer Auth Integration

Choose this when

Use this path when your Next.js App Router product owns the sign-in UI and wants Lamba to provide customer identity, scoped sessions, Project roles, and Customer API reads.

This guide uses the public customer hosts only:

• https://test.id.uselamba.com or https://id.uselamba.com for auth and session operations
• https://test.api.uselamba.com or https://api.uselamba.com for Customer API reads

Before you start

You need:

• a Lamba Workspace
• a Lamba Project
• the selected environment, usually test while integrating
• a Next.js App Router app
• one server route for each auth action your UI exposes

Do not send console-only workspace, project, or environment headers from your product. Public customer requests are scoped by the bearer token and by POST /v1/sessions/switch-context.

Get credentials from Console

Open the Lamba console and use the top Workspace / Project selector first. Then open the selected Project and environment you are integrating.

Configure environment variables

LAMBA_CUSTOMER_AUTH_BASE_URL=https://test.id.uselamba.com
LAMBA_CUSTOMER_API_BASE_URL=https://test.api.uselamba.com
LAMBA_CUSTOMER_WORKSPACE_ID=<workspace-id>
LAMBA_CUSTOMER_PROJECT_ID=<project-id>
LAMBA_CUSTOMER_ENV=test
LAMBA_SESSION_COOKIE=lamba_access_token
LAMBA_REFRESH_COOKIE=lamba_refresh_token

Use production hosts and production credentials only after the sandbox flow works end to end.

Make the first request

Start with password login if your Project has password auth enabled. Your browser posts to your own Next.js route. That route calls Lamba server-side and stores returned tokens in HttpOnly cookies.

// src/lib/lamba-customer.ts
import "server-only";

export async function customerAuthFetch(path: string, init?: RequestInit) {
  return fetch(`${process.env.LAMBA_CUSTOMER_AUTH_BASE_URL}${path}`, {
    cache: "no-store",
    headers: { "content-type": "application/json", ...(init?.headers ?? {}) },
    ...init,
  });
}

export async function customerApiFetch(path: string, accessToken: string) {
  return fetch(`${process.env.LAMBA_CUSTOMER_API_BASE_URL}${path}`, {
    cache: "no-store",
    headers: { authorization: `Bearer ${accessToken}` },
  });
}

// src/app/api/auth/login/password/route.ts
import { cookies } from "next/headers";
import { NextResponse } from "next/server";
import { customerAuthFetch } from "@/lib/lamba-customer";

export async function POST(request: Request) {
  const payload = await request.json();
  const response = await customerAuthFetch("/v1/auth/login/password", {
    method: "POST",
    body: JSON.stringify(payload),
  });
  const body = await response.json();

  if (!response.ok) {
    return NextResponse.json(body, { status: response.status });
  }

  const cookieStore = await cookies();
  cookieStore.set("lamba_access_token", body.access_token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    path: "/",
  });
  cookieStore.set("lamba_refresh_token", body.refresh_token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    path: "/",
  });

  return NextResponse.json({ ok: true });
}

Request fields

For POST /v1/auth/login/password:

For POST /v1/sessions/switch-context after login:

Response fields

Login, refresh, and switch-context responses use the same token shape:

GET /v1/me/context is the simplest Customer API proof:

Read protected pages

After setting cookies, call the Customer API from server components or route handlers.

// src/app/app/page.tsx
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { customerApiFetch } from "@/lib/lamba-customer";

export default async function AppPage() {
  const cookieStore = await cookies();
  const token = cookieStore.get("lamba_access_token")?.value;

  if (!token) {
    redirect("/login");
  }

  const response = await customerApiFetch("/v1/me/context", token);
  if (!response.ok) {
    redirect("/login");
  }

  const context = await response.json();
  return <main>Signed in as {context.user.email}</main>;
}

Done when

Troubleshooting

Related docs

• Hosted Auth Integration: /docs/quickstart/hosted-auth
• OIDC Integration: /docs/quickstart/oidc
• Customer API request and response contract: /docs/quickstart/customer-api
• Error Reference: /docs/reference/errors