Skip to content

// auth and identity

Via API

WorkOS email verification with pingutil

AuthKit lets anyone self-register with email unless you add rules, and B2B apps end up with personal and throwaway accounts beside real teams. A user registration Action receives the sign-up before WorkOS completes it; your endpoint calls pingutil and returns a signed Allow or Deny, with an error message the user sees.

Where it connects: WorkOS AuthKit Actions, user registration action

What goes wrong without it

  • Our B2B product gets self-serve sign-ups from temp-mail addresses that will never become a paying team.
  • We want work emails steered into organizations, but AuthKit does not tell us who a domain belongs to.
  • If our Actions endpoint fails, WorkOS denies the sign-up by default, so the check has to be fast and must not throw.

What you can do with WorkOS and pingutil

  • Deny disposable registrations

    For verdict.is_spam, sign a Deny verdict with errorMessage. WorkOS shows the message and does not create the user.

  • Require a work email on team plans

    For category free or isp, deny with "Please use a work email address", the same pattern WorkOS uses in its own docs example, but driven by pingutil's webmail and ISP lists instead of a hard-coded domain.

  • Attach the company after sign-up

    Once the user is allowed, a background full lookup returns company.name and company.industry for routing to sales or matching an existing organization.

Set it up

  1. 1

    In the WorkOS Dashboard, enable Actions, add a user registration action endpoint pointing to your route, and copy the Actions secret.

  2. 2

    Set WORKOS_API_KEY, WORKOS_ACTIONS_SECRET and PINGUTIL_KEY in your environment.

  3. 3

    Add the route below; it verifies the WorkOS-Signature header and always returns a signed verdict.

  4. 4

    Decide the endpoint's failure behavior in the dashboard; the default is to deny when WorkOS cannot reach your endpoint.

  5. 5

    Register with a disposable address and confirm the error message appears in AuthKit.

app/api/workos/actions/route.ts
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const secret = process.env.WORKOS_ACTIONS_SECRET!;

async function lookup(email: string) {
  try {
    const res = await fetch('https://pingutil.com/v1/lookup', {
      method: 'POST',
      headers: {
        authorization: 'Bearer ' + process.env.PINGUTIL_KEY,
        'content-type': 'application/json',
      },
      body: JSON.stringify({ input: email, skip_enrichment: true }),
      signal: AbortSignal.timeout(1500),
    });
    return res.ok ? await res.json() : null;
  } catch {
    return null;
  }
}

export async function POST(req: Request) {
  const payload = await req.json();
  const action = await workos.actions.constructAction({
    payload,
    sigHeader: req.headers.get('workos-signature')!,
    secret,
  });

  let verdict: 'Allow' | 'Deny' = 'Allow';
  let errorMessage: string | undefined;

  if (action.object === 'user_registration_action_context') {
    const data = await lookup(action.userData.email);
    if (data?.verdict.is_spam) {
      verdict = 'Deny';
      errorMessage = 'Please sign up with a permanent email address.';
    }
  }

  const response = await workos.actions.signResponse(
    { type: 'user_registration', verdict, ...(errorMessage ? { errorMessage } : {}) },
    secret,
  );
  return Response.json(response);
}

What to do with each result

pingutil resultAction in WorkOS
verdict.is_spam: trueSigned Deny with errorMessage
category: "free" or "isp" (team-only plans)Signed Deny asking for a work email
category: "company"Signed Allow; look up the company in the background
Timeout, 429 or 5xxSigned Allow, so WorkOS's deny-on-error default never kicks in

Limits to plan for

  • WorkOS waits for your endpoint during registration and denies by default if it cannot reach it or validate the response. Keep the pingutil timeout short and always return a signed verdict.
  • Fast mode catches disposable and randomized addresses, not dead mailboxes. AuthKit's own email verification still covers mailbox reachability.
  • pingutil's free webmail list is about 100 provider domains. A small regional webmail domain can come back as company.

WorkOS documentation

WorkOS is a trademark of its owner. This integration uses WorkOS's documented extension points; it is not an official WorkOS app.

Common questions

What happens if pingutil is slow during an AuthKit sign-up?
The lookup aborts after 1.5 seconds and the route signs an Allow verdict, so the user gets in unscreened rather than locked out.
Can I use the company profile to put users in the right organization?
Yes, but not in the Action itself. Drop skip_enrichment in a background job after registration; first-seen domains take a few seconds to profile.

Stop bad addresses in WorkOS today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your WorkOS setup will receive.