// auth and identity
Via APIWorkOS 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
In the WorkOS Dashboard, enable Actions, add a user registration action endpoint pointing to your route, and copy the Actions secret.
- 2
Set WORKOS_API_KEY, WORKOS_ACTIONS_SECRET and PINGUTIL_KEY in your environment.
- 3
Add the route below; it verifies the WorkOS-Signature header and always returns a signed verdict.
- 4
Decide the endpoint's failure behavior in the dashboard; the default is to deny when WorkOS cannot reach your endpoint.
- 5
Register with a disposable address and confirm the error message appears in AuthKit.
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 result | Action in WorkOS |
|---|---|
| verdict.is_spam: true | Signed 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 5xx | Signed 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.