Migrate from Auth0

This guide covers migrating from Auth0 to Wocha, including users, connections, and application configuration.

Overview

Auth0 Concept	Wocha Equivalent
Tenant	Tenant
Application	Application
Connection	Connection
Organization	Organisation
Action	Action
Rule (deprecated)	Token Rule
API (audience)	Product
Role/Permission	SpiceDB Permission
Log Stream	Event Stream / Webhook
Management API	Customer API
Universal Login	Hosted Login (Kratos)

Step 1: Create your Wocha tenant

npx @wocha/cli init --cloud

Step 2: Export users from Auth0

Use the Auth0 Management API or Dashboard to export your users:

auth0 users export --format json --fields "user_id,email,name,created_at"

Step 3: Import users to Wocha

CLI migration (recommended)

Always preview the migration first:

export WOCHA_MANAGEMENT_API_KEY=wocha_mgmt_...
export WOCHA_TENANT=your-tenant
 
wocha migrate auth0 --dry-run
wocha migrate auth0

The --dry-run flag parses and validates Auth0 users without creating anything in Wocha. It reports user counts, duplicate emails, and missing fields, and writes a JSON migration plan to wocha-migrate-plan-auth0-*.json.

After import, verify the migration:

wocha migrate auth0 --validate

Validation checks that all Auth0 users exist in Wocha (matched by email) and reports any discrepancies.

Manual import via SDK

import { WochaClient } from '@wocha/sdk';
 
const wocha = new WochaClient({
  apiKey: process.env.WOCHA_API_KEY!,
  tenant: process.env.WOCHA_TENANT!,
});
 
for (const user of auth0Users) {
  await wocha.users.create({
    email: user.email,
    name: user.name,
    metadata: { auth0_id: user.user_id },
  });
}

Step 4: Configure connections

Map your Auth0 connections to Wocha:

Social connections (Google, GitHub, etc.) — configure in Console under Connections > Social
Enterprise SSO (SAML, OIDC) — configure in Console under Connections > Enterprise
SCIM directories — configure in Console under Connections > SCIM

Step 5: Update your application

Replace Auth0 SDK with Wocha SDK:

Next.js

npm uninstall @auth0/nextjs-auth0
npm install @wocha/nextjs

Replace the Auth0 handler:

// Before (Auth0)
import { handleAuth } from '@auth0/nextjs-auth0';
export const GET = handleAuth();
 
// After (Wocha)
import { createWochaHandler } from '@wocha/nextjs';
const handler = createWochaHandler();
export const GET = handler;
export const POST = handler;

React SPA

npm uninstall @auth0/auth0-react
npm install @wocha/react

Step 6: Migrate webhooks

Auth0 Actions/Log Streams map to Wocha webhooks:

const wocha = new WochaClient({ apiKey, tenant });
await wocha.webhooks.create({
  url: 'https://your-app.com/webhooks/wocha',
  events: ['user.created', 'user.updated', 'session.created'],
});

Step 7: Update environment variables

Auth0	Wocha
`AUTH0_SECRET`	`WOCHA_SECRET`
`AUTH0_BASE_URL`	`NEXT_PUBLIC_APP_URL`
`AUTH0_ISSUER_BASE_URL`	`WOCHA_ISSUER`
`AUTH0_CLIENT_ID`	`WOCHA_CLIENT_ID`
`AUTH0_CLIENT_SECRET`	`WOCHA_CLIENT_SECRET`

Step 8: Test and verify

npx @wocha/cli doctor
npx @wocha/cli test-login

Migrate from Auth0

On this page