Skip to content

// auth and identity

Via API

Okta email verification with pingutil

Okta self-service registration accepts any syntactically valid address, so throwaway and scripted accounts land in your directory. A registration inline hook can deny the sign-up before Okta creates the user; calling pingutil in fast mode from that hook gives a disposable and randomness verdict well inside Okta's 3-second timeout.

Where it connects: Okta registration inline hook (self-service registration)

What goes wrong without it

  • Our customer-facing Okta org gets bursts of sign-ups from random strings at temp-mail domains.
  • Security wants scripted registrations stopped at the door, not cleaned up by an admin every Monday.
  • The only domain logic Okta gives us out of the box is what we write in the hook ourselves.

What you can do with Okta and pingutil

  • Deny throwaway domains at self-service registration

    POST /v1/lookup with skip_enrichment: true returns verdict.is_spam: true for disposable domains. The hook answers with registration DENY and an errorSummary the user sees.

  • Stop machine-generated local parts

    Bots tend to register addresses like ccjxx90sze@. email_signals.is_randomized and verdict.reason randomized_local_part catch them even on domains that are not on any list.

  • Flag role and shared mailboxes

    verdict.low_trust marks role, system and sales-outreach addresses. Allow them, but log the address so your team can review who registered with info@ or noreply@.

Set it up

  1. 1

    Deploy the endpoint below on HTTPS and set PINGUTIL_KEY and OKTA_HOOK_SECRET in its environment.

  2. 2

    In the Okta Admin Console, go to Workflow > Inline Hooks, add a Registration inline hook with your endpoint URL, and set the authentication field to authorization with OKTA_HOOK_SECRET as the secret.

  3. 3

    Open your profile enrollment policy and select the hook under the inline hook setting for self-service registration.

  4. 4

    Register with a disposable address and confirm Okta shows your error message.

  5. 5

    Watch the hook's call results in the Okta System Log while you test.

Registration inline hook endpoint (Express)
import express from 'express';

const app = express();
app.use(express.json());

const update = (registration: 'ALLOW' | 'DENY') => ({
  commands: [{ type: 'com.okta.action.update', value: { registration } }],
});

app.post('/okta/registration-hook', async (req, res) => {
  // Okta sends the authentication field and secret you set on the hook.
  if (req.get('authorization') !== process.env.OKTA_HOOK_SECRET) return res.status(401).end();

  const email: string | undefined = req.body?.data?.userProfile?.email;
  if (!email) return res.json(update('ALLOW'));

  try {
    const r = await fetch('https://pingutil.com/v1/lookup', {
      method: 'POST',
      headers: {
        authorization: 'Bearer ' + process.env.PINGUTIL_KEY,
        'content-type': 'application/json',
      },
      // Fast mode: no AI call, answers in milliseconds.
      body: JSON.stringify({ input: email, skip_enrichment: true }),
      signal: AbortSignal.timeout(1500), // Okta waits 3 s in total
    });
    if (!r.ok) return res.json(update('ALLOW')); // fail open
    const data = await r.json();

    if (data.verdict?.is_spam) {
      const message = 'Please register with a permanent email address.';
      return res.json({
        ...update('DENY'),
        error: {
          errorSummary: message,
          errorCauses: [{
            errorSummary: message,
            reason: 'INVALID_EMAIL_DOMAIN',
            locationType: 'body',
            location: 'data.userProfile.email',
            domain: 'end-user',
          }],
        },
      });
    }
    if (data.verdict?.low_trust) console.info('okta registration low_trust', data.verdict.reason);
    return res.json(update('ALLOW'));
  } catch {
    return res.json(update('ALLOW'));
  }
});

app.listen(3000);

What to do with each result

pingutil resultAction in Okta
verdict.is_spam: true, reason "disposable_domain"Return registration DENY with an errorSummary
verdict.is_spam: true, reason "randomized_local_part"Return registration DENY
verdict.low_trust: trueReturn ALLOW and log the reason for review
category: "free" or "company"Return ALLOW
Timeout, 429 or 5xxReturn ALLOW (fail open)

Limits to plan for

  • Okta gives inline hooks a 3-second timeout with at most one retry. That rules out a full mailbox check in the hook; use fast-mode /v1/lookup there and run /v1/verify later if you need mailbox status.
  • The hook only sees self-service registration and progressive profiling. Users created by admins, imports or SCIM do not pass through it.
  • Fast mode relies on the disposable list and local-part heuristics. A brand-new throwaway domain with a normal-looking name can pass until the list catches up.

Okta documentation

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

Common questions

Why not run a full mailbox check from the Okta hook?
Okta stops waiting after 3 seconds, and a mailbox check on a slow mail server can take longer. Fast-mode lookup returns in milliseconds and catches the disposable and scripted sign-ups that cause most of the damage.
Does denying in the hook create a partial user?
No. Per Okta's registration inline hook guide, a DENY response stops the registration and Okta shows your errorSummary to the user.

Stop bad addresses in Okta 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 Okta setup will receive.