API Route Handlers

The ZewstID SDK provides pre-built API route handlers for all authentication methods. These handlers integrate with NextAuth and automatically establish SSO sessions.

Quick Setup

Create a single file to handle all authentication endpoints:

Copy
// app/api/zewstid/[...zewstid]/route.ts
import { createZewstIDHandlers } from '@zewstid/nextjs/handlers';

const handlers = createZewstIDHandlers({
  clientId: process.env.ZEWSTID_CLIENT_ID!,
  clientSecret: process.env.ZEWSTID_CLIENT_SECRET!,
});

export const GET = handlers.GET;
export const POST = handlers.POST;

This creates all these endpoints automatically:

Configuration Options

Copy
createZewstIDHandlers({
  // Required
  clientId: process.env.ZEWSTID_CLIENT_ID!,

  // Optional - Client secret (required for confidential clients)
  clientSecret: process.env.ZEWSTID_CLIENT_SECRET,

  // Optional - Your app's base URL (defaults to NEXTAUTH_URL)
  baseUrl: process.env.NEXTAUTH_URL,

  // Optional - ZewstID API URL (defaults to https://api.zewstid.com)
  apiUrl: 'https://api.zewstid.com',

  // Optional - ZewstID Auth URL (defaults to https://auth.zewstid.com/realms/zewstid)
  issuerUrl: 'https://auth.zewstid.com/realms/zewstid',

  // Optional - NextAuth secret (defaults to NEXTAUTH_SECRET env var)
  nextAuthSecret: process.env.NEXTAUTH_SECRET,

  // Optional - Enable/disable SSO establishment (default: true)
  enableSSOEstablishment: true,
});

Endpoint Details

Check Email

Check if a user exists in ZewstID.

Request:

Copy
POST /api/zewstid/check-email
Content-Type: application/json

{
  "email": "user@example.com"
}

Response:

Copy
{
  "exists": true,
  "userId": "abc123"
}

Get Auth Methods

Get available authentication methods for a user.

Request:

Copy
POST /api/zewstid/methods
Content-Type: application/json

{
  "email": "user@example.com"
}

Response:

Copy
{
  "methods": {
    "password": true,
    "otp": true,
    "magicLink": true,
    "passkey": false,
    "push": false
  },
  "mfa": {
    "enabled": true,
    "totp": true,
    "push": false
  },
  "userId": "abc123"
}

Password Authentication

Authenticate with email and password.

Request:

Copy
POST /api/zewstid/password
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Success Response:

Copy
{
  "success": true,
  "redirectUrl": "/api/zewstid/establish-sso?callbackUrl=/dashboard",
  "user": {
    "email": "user@example.com",
    "name": "John Doe"
  }
}

MFA Required Response:

Copy
{
  "success": true,
  "mfaRequired": true,
  "mfaSessionId": "mfa_session_abc123",
  "redirectUrl": null
}

Send OTP

Send a one-time password via email.

Request:

Copy
POST /api/zewstid/otp/send
Content-Type: application/json

{
  "email": "user@example.com"
}

Response:

Copy
{
  "success": true,
  "message": "OTP sent"
}

Verify OTP

Verify a one-time password.

Request:

Copy
POST /api/zewstid/otp/verify
Content-Type: application/json

{
  "email": "user@example.com",
  "code": "123456"
}

Response:

Copy
{
  "success": true,
  "redirectUrl": "/api/zewstid/establish-sso?callbackUrl=/dashboard",
  "user": {
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Send Magic Link

Send a magic link email.

Request:

Copy
POST /api/zewstid/magic-link/send
Content-Type: application/json

{
  "email": "user@example.com",
  "callbackUrl": "/dashboard"
}

Response:

Copy
{
  "success": true,
  "message": "Magic link sent"
}

Verify Magic Link

Verify a magic link token.

Request:

Copy
POST /api/zewstid/magic-link/verify
Content-Type: application/json

{
  "token": "magic_link_token_abc123"
}

Response:

Copy
{
  "success": true,
  "redirectUrl": "/api/zewstid/establish-sso?callbackUrl=/dashboard",
  "user": {
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Verify MFA

Verify a TOTP code for MFA.

Request:

Copy
POST /api/zewstid/mfa/verify
Content-Type: application/json

{
  "mfaSessionId": "mfa_session_abc123",
  "method": "totp",
  "code": "123456"
}

Response:

Copy
{
  "verified": true,
  "redirectUrl": "/api/zewstid/establish-sso?callbackUrl=/dashboard",
  "user": {
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Establish SSO

Redirects to establish a ZewstID SSO session. This endpoint is called automatically after successful authentication.

Request:

Copy
GET /api/zewstid/establish-sso?callbackUrl=/dashboard

This endpoint:

1. Reads the ID token from a cookie set during authentication
2. Redirects to the client-side SSO establishment page
3. The client page calls NextAuth's
   Copy

   signIn()
   with
   Copy

   prompt=none
   and
   Copy

   id_token_hint
4. ZewstID establishes the SSO session without requiring re-authentication
5. User is redirected to the callback URL

SSO Flow

After successful direct authentication (password, OTP, magic link), the SDK automatically establishes a ZewstID SSO session:

Copy
1. User authenticates via password/OTP/magic-link
2. API returns tokens + sets id_token cookie
3. Client redirects to /api/zewstid/establish-sso
4. establish-sso redirects to /establish-sso page
5. Client page calls signIn('zewstid', {}, { prompt: 'none', id_token_hint })
6. ZewstID validates token and sets SSO cookie
7. User is redirected to callback URL
8. User is now signed in with full SSO

This enables:

• Cross-Portal SSO: Sign in once, access all connected apps
• Silent Authentication: Navigate between apps without re-authenticating
• Session Sharing: All ZewstID apps share the same session

Error Handling

All endpoints return consistent error responses:

Copy
{
  "error": "error_code",
  "error_description": "Human-readable error message"
}

Common error codes:

• Copy

  invalid_request
  - Missing required fields
• Copy

  invalid_credentials
  - Wrong email/password
• Copy

  user_not_found
  - Email not registered
• Copy

  invalid_code
  - Wrong OTP or MFA code
• Copy

  expired_token
  - Magic link or session expired
• Copy

  rate_limited
  - Too many requests

Using with SignIn Components

The handlers work seamlessly with the SDK's SignIn components:

Copy
// app/signin/page.tsx
import { SignIn } from '@zewstid/nextjs';

export default function SignInPage() {
  return (
    <SignIn
      apiBasePath="/api/zewstid" // Points to your handlers
      callbackUrl="/dashboard"
    />
  );
}

The SignIn component automatically calls the correct handler endpoints.

Custom API Path

If you need a different API path:

Copy
// app/api/auth/zewst/[...path]/route.ts
import { createZewstIDHandlers } from '@zewstid/nextjs/handlers';

const handlers = createZewstIDHandlers({
  clientId: process.env.ZEWSTID_CLIENT_ID!,
});

export const GET = handlers.GET;
export const POST = handlers.POST;

Then update your SignIn component:

Copy
<SignIn apiBasePath="/api/auth/zewst" />

Related

• SignIn Components - Pre-built UI components
• Authentication Methods - All auth method APIs
• Troubleshooting - Common issues