Getting started

Time to first auth: ~2 minutes. Run one command, start your dev server, and click Sign in — no Console setup, no redirect URI configuration, and no hand-edited layout files.

Quick start (recommended)

The fastest path is the Wocha CLI. It detects your framework, provisions a free development tenant, installs the SDK, and scaffolds auth files for you.

One-command setup

npx @wocha/cli init -y

Pass --framework to skip prompts — for example nextjs, react-spa, vue, or sveltekit.

Example output

Detected Next.js project.

  Installing @wocha/nextjs... done
  Creating app/api/auth/[...wocha]/route.ts... done
  Creating middleware.ts... done
  Updating app/layout.tsx... done (provider + auth header added)
  Finishing tenant provisioning… done (3.2s)
  ✓ Wrote .wocha/credentials.json
  ✓ Updated .env.local

You're ready!

Your development tenant is configured:
  Tenant URL   https://my-app-dev-a1b2c3.wocha.ai
  Console      https://my-app-dev-a1b2c3.console.wocha.ai
  Framework    nextjs

Next steps:
  1. Run your dev server (npm run dev / pnpm dev)
  2. Visit http://localhost:3000 — sign-in links are in the header
  3. Run `wocha dev` for webhooks and the dev dashboard

The CLI registers common localhost redirect URIs automatically, so OAuth callbacks work on ports 3000, 3001, 4000, and 5173 without manual configuration.

What you get

Sign in / Sign up links in your app header (visible on first load)
Public-by-default routes — only paths you opt into (e.g. /dashboard/*) require authentication
Encrypted session cookies via the BFF route handler
Claim later — run wocha claim to keep your development tenant permanently

Start your dev server (pnpm dev).
Open the app — you should see Sign in in the header.
Complete login on the hosted auth UI.
Confirm you return with an active session and your email shown in the header.

Troubleshooting:

redirect_uri_mismatch — if you use a non-standard port, run wocha doctor or check .env.local for WOCHA_REDIRECT_URI.
invalid_client — re-run wocha init or wocha cloud-dev to refresh credentials.
Session not persisting — ensure WOCHA_COOKIE_SECRET is set in production.

Next steps

Next.js quickstart — framework-specific details
API reference — explore the Customer API interactively
Webhooks overview — receive lifecycle events
TypeScript SDK — manage users and organisations server-side

Alternative: Manual setup via the Console

Use this path if you prefer to configure credentials yourself or are integrating an existing Wocha project.

1. Create your account

Go to wocha.ai/signup and register with email/password or a social provider (Google, GitHub, Microsoft). Email verification is required before you can create a project.

2. Create a project

After sign-in you land in the Wocha Console project wizard:

Field	Notes
Project name	Display name (3–100 chars)
Slug	Becomes `{slug}.auth.wocha.ai`
Region	EU (default), US, or APAC
Plan	Free tier is fine for development

Provisioning takes ~5 seconds. Your project gets an isolated tenant schema, default OAuth application, and management API key.

3. Collect credentials

From the Console dashboard or project settings, copy:

Credential	Where to find it	Used for
Tenant slug / ID	Project overview	Issuer URL, API calls
Management API key	Shown once at creation	`@wocha/sdk` (server-side admin)
Client ID & secret	Applications → Quickstart app	OAuth in your app
Issuer URL	`https://{slug}.auth.wocha.ai`	SDK config

Next.js: http://localhost:3000/api/auth/callback
React SPA: http://localhost:5173/callback

4. Install the SDK

pnpm add @wocha/nextjs

Or choose the package for your stack:

Stack	Package
Next.js App Router	`@wocha/nextjs`
React SPA (Vite, CRA)	`@wocha/react`
Server / scripts	`@wocha/sdk`

5. Configure environment variables

.env.local

WOCHA_CLIENT_ID=your-client-id
WOCHA_CLIENT_SECRET=your-client-secret
WOCHA_ISSUER=https://your-tenant.auth.wocha.ai

6. Wire up auth

See the framework quickstart that matches your stack:

Getting started

On this page