Get started

Environment variables and credentials

Client ID, API key and API URL: where they come from and which may reach the browser.

Where to find them#

Each environment of a project (development and production) has its own client ID, API keys, signing keys, users and branding. Open the environment in the dashboard: the client ID is on its overview, API keys are under API keys. A key can be revealed again later; every reveal is recorded in the environment's audit log.

Variables#

Name	Secret?	Used for
`AUTH_CLIENT_ID`	No	Identifies the environment: the key set tokens are verified against, and the session cookie name (<client id>_session).
`AUTH_API_KEY`	Yes, server only	Redeems sign-in codes, refreshes sessions, and calls the API on your behalf.
`AUTH_API_URL`	No	Your authentication API origin. Required in production: without it the SDK refuses to start rather than fall back to the development API.
`NEXT_PUBLIC_AUTH_REDIRECT_URI`	No	Where users land after sign-in when no return path was requested. The examples pass it explicitly as redirectUri.
`AUTH_WEBHOOK_SECRET`	Yes, server only	The whsec_… secret of a webhook endpoint, if you receive webhooks.
`AUTH_COOKIE_PASSWORD`	Yes, server only	Encrypts the access and refresh tokens stored in session cookies. Use at least 32 characters.

lib/auth-config.tstype-checked

// lib/auth-config.ts — server-only. Import it from route handlers,
// middleware and Server Components; never from a Client Component.
import type { AuthConfig } from '@3een/auth';

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is not set`);
  return value;
}

export const authConfig: AuthConfig = {
  // Browser-safe: identifies your environment and names the session cookie.
  clientId: required('AUTH_CLIENT_ID'),
  // Secret: redeems sign-in codes and calls the API. Server only.
  apiKey: required('AUTH_API_KEY'),
  // Your environment's authentication API origin.
  apiUrl: required('AUTH_API_URL'),
  // Where users land after signing in when no return path was requested.
  redirectUri: required('NEXT_PUBLIC_AUTH_REDIRECT_URI'),
};

Browser-safe and server-only#

The API key and the webhook secret stay on the server: in route handlers, middleware, Server Components and your own backend. Never put them in a NEXT_PUBLIC_ variable or pass them to a Client Component.
The client ID and the API URL are not secrets. They still don't need to reach the browser: the components talk to your own /api/auth routes, not to the API.
Session tokens live in httpOnly cookies the SDK sets. Browser JavaScript never sees them.

Rotating an API key#

Create a new key, deploy it, then revoke the old one in the dashboard. Revocation takes effect at once. Each create, reveal and revoke is recorded in the environment's audit log and sent as an api_key.* webhook event.