Prerequisites

Before using this integration, you need:

1. An Autheona account: Sign up
2. An Autheona project. Use a Sandbox project for testing and a Production project for live applications. See the Quick Start Guide.
3. An Autheona access token for the project. See the Access Tokens documentation.
4. An Auth0 tenant with Auth0 Actions available.

Autheona access tokens provide access to the Autheona API. Store the token securely using an Auth0 Action Secret. Never hardcode an access token in your Action source code.

Pre User Registration

Use a Pre User Registration Action when you want to evaluate an email address before Auth0 creates the user.

This is generally the appropriate integration point when your primary goal is preventing disposable, suspicious, or otherwise disallowed email addresses from registering.

Auth0 Action Code

Create a new Action in: Auth0 Dashboard -> Actions -> Library -> Create Action

Select the Pre User Registration trigger.

exports.onExecutePreUserRegistration = async (event, api) => {
  const email = event.user.email;
  if (!email) {
    api.validation.error("missing_email", "An email address is required.");
    return;
  }

  const apiKey = event.secrets.AUTHEONA_API_KEY;
  if (!apiKey) {
    console.log("Autheona access token is not configured");
    return;
  }

  const normalizedEmail = email.toLowerCase().trim();

  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 3000);

  try {
    const response = await fetch("https://api.autheona.com/v1/intelligence", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": apiKey,
      },
      body: JSON.stringify({
        email_address: normalizedEmail,
      }),
      signal: controller.signal,
    });

    if (!response.ok) {
      console.log(`Autheona API error: ${response.status}`);
      return;
    }

    const result = await response.json();
    if (result.action === "block") {
      api.validation.error(
        "email_not_allowed",
        "Email address is not allowed.",
      );

      return;
    }

    console.log(
      `Autheona returned action "${result.action}" for ${normalizedEmail}`,
    );
  } catch (error) {
    console.log(`Autheona validation error: ${error.message}`);
  } finally {
    clearTimeout(timeout);
  }
};

Failure behavior

The example above uses a fail-open strategy:

• If Autheona returns block, registration is denied.
• If Autheona returns allow or ignore, registration continues.
• If Autheona is temporarily unavailable, times out, or returns an HTTP error, registration continues.

This behavior is intentional. It prevents an Autheona outage from automatically becoming an outage of your registration system.

If your security requirements require fail-closed behavior, change the error-handling branches so that the registration is denied when Autheona cannot be reached or returns an unexpected error.

Auth0 supports denying registration from a Pre User Registration Action through api.access.deny() or api.validation.error(). api.validation.error() is useful when you want to provide a custom validation error. See the Auth0 Pre User Registration documentation.

Post Login

Use a Post Login Action when you want Autheona to evaluate the user's email during authentication.

Create a new Action in: Auth0 Dashboard -> Actions -> Library -> Create Action

Select the Login / Post Login trigger.

Auth0 Action Code

exports.onExecutePostLogin = async (event, api) => {
  const email = event.user.email;
  if (!email) {
    return;
  }

  const apiKey = event.secrets.AUTHEONA_API_KEY;
  if (!apiKey) {
    console.log("Autheona access token is not configured");
    return;
  }

  const normalizedEmail = email.toLowerCase().trim();

  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 3000);

  try {
    const response = await fetch("https://api.autheona.com/v1/intelligence", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": apiKey,
      },
      body: JSON.stringify({
        email_address: normalizedEmail,
      }),
      signal: controller.signal,
    });

    if (!response.ok) {
      console.log(`Autheona API error: ${response.status}`);
      return;
    }

    const result = await response.json();
    if (result.action === "block") {
      api.access.deny(
        "Your email address cannot be used to access this application.",
      );

      return;
    }

    if (result.action !== "allow" && result.action !== "ignore") {
      console.log(`Unexpected Autheona action: ${result.action}`);
      return;
    }

    api.user.setAppMetadata("autheona_checked", true);
    api.user.setAppMetadata("autheona_action", result.action);

    console.log(
      `Autheona returned action "${result.action}" for ${normalizedEmail}`,
    );
  } catch (error) {
    console.log(`Autheona validation error: ${error.message}`);
  } finally {
    clearTimeout(timeout);
  }
};

Failure behavior

The Post Login example also uses a fail-open strategy:

• block: deny the login.
• allow: allow the login.
• ignore: allow the login.
• Autheona unavailable: allow the login.
• Autheona request timeout: allow the login.
• Autheona HTTP error: allow the login.

If your application requires fail-closed behavior, change the error-handling branches accordingly.

Auth0 documents api.access.deny() as the mechanism for preventing the user from completing the login flow. Calling it also stops subsequent Actions in the same flow from executing. See the Auth0 Post Login documentation.

Configuration

Create the Action

For registration protection

Go to: Auth0 Dashboard -> Actions -> Library -> Create Action -> Pre User Registration

Paste the Pre User Registration code above.

For login protection

Go to: Auth0 Dashboard -> Actions -> Library -> Create Action -> Login / Post Login

Paste the Post Login code above. Save the Action.

Add the Autheona Secret

In the Action editor:

1. Open the Secrets section.
2. Click Add Secret or Create Secret.
3. Set the key to:

AUTHEONA_API_KEY

4. Set the value to your Autheona access token.
5. Save the secret.

Do not put the actual token directly into the JavaScript source code.

Autheona access tokens are displayed only when they are created, so store the token securely when you create it. If a token is exposed, revoke it and create a replacement. See the Autheona Access Tokens documentation.

Add the Action to the Correct Auth0 Flow

Pre User Registration

Go to: Auth0 Dashboard -> Actions -> Flows -> Pre User Registration

Then:

1. Click Add Action.
2. Select your Autheona Action.
3. Add it to the flow.
4. Click Apply.

Post Login

Go to: Auth0 Dashboard -> Actions -> Flows -> Login

Then:

1. Click Add Action.
2. Select your Autheona Post Login Action.
3. Place it at the appropriate position in the Login flow.
4. Click Apply.

The Action itself is the trigger handler; you do not add a separate "Post Login trigger" to the flow.

Testing With a Custom Policy

For testing and development, you can provide a custom_policy in the Autheona request. For example:

const customPolicy = {
  parent_rules: [
    {
      action: "block",
      field: "domain_disposable",
      operator: "==",
      target: {
        bool: true,
      },
    },
  ],
  stop_on_block: true,
  version: "1.0",
};

const response = await fetch("https://api.autheona.com/v1/intelligence", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
  },
  body: JSON.stringify({
    email_address: normalizedEmail,
    custom_policy: customPolicy,
  }),
});

See the Autheona Policy Editor documentation.

User App Metadata

The Post Login example stores only the final Autheona decision in Auth0 app_metadata.

The fields are:

Example:

const autheonaChecked = event.user.app_metadata?.autheona_checked;

const autheonaAction = event.user.app_metadata?.autheona_action;

Auth0 supports api.user.setAppMetadata() in Actions for storing application metadata. Metadata changes requested by Actions are persisted as part of the Action flow. See the Auth0 metadata documentation.

Do not store the entire Autheona intelligence response in Auth0 metadata unless you have a specific requirement to do so. Store only the information your application actually needs.

Understanding Autheona Actions

The User Trust API returns an action representing the policy result. The commonly used actions are:

• allow: Allow the request to continue.
• block: Block the request.
• ignore: Do not block the request based on the returned policy decision.

Your application should decide what each action means for its own workflow.

For example:

flowchart TD
  A[Pre User Registration] --> B{Autheona}
  B -->|block| C[Registration denied]
  B -->|allow| D[Registration continues]
  B -->|ignore| D

For Post Login:

flowchart TD
  A[Login] --> B{Autheona}
  B -->|block| C[Login denied]
  B -->|allow| D[Login continues]
  B -->|ignore| D

Do not automatically interpret ignore as "manual review required" unless your application actually implements a review workflow.

API Errors and Rate Limits

The Autheona API uses the following HTTP response categories:

Autheona currently documents a rate limit of 10 requests per second per access token. Production integrations should avoid unnecessary retries and should handle transient rate-limit or server errors appropriately.

See the Autheona API Reference.

Timeout and Retry Considerations

The examples use a 3-second request timeout to prevent an external API request from waiting indefinitely.

The timeout is an example value. Adjust it based on your application's authentication and registration requirements.

If you implement retries:

• Retry only transient failures.
• Do not blindly retry authentication failures such as HTTP 401.
• Avoid excessive retries during user authentication.
• Consider Autheona rate limits and API quotas.
• Use exponential backoff where appropriate.

For many authentication flows, a short timeout with a deliberate fail-open or fail-closed policy is preferable to an unrestricted retry loop.

Choosing the Correct Auth0 Trigger

Use Pre User Registration when your primary requirement is:

Do not allow this email address to create an Auth0 user.

Use Post Login when your primary requirement is:

Evaluate this user's email when they authenticate and deny access when the Autheona policy says to block.

You may use both triggers if your security model requires both registration-time and authentication-time evaluation, but understand that this can result in multiple Autheona API calls for the same user.

Production Recommendations

Before deploying this integration to production:

• Keep the Autheona access token in an Auth0 Secret.
• Never hardcode the token in Action source code.
• Use a Production Autheona project for live traffic.
• Configure production policies in the Autheona Policy Editor.
• Test the allow, block, and ignore outcomes.
• Test Autheona API failures and timeouts.
• Decide explicitly whether your integration should fail open or fail closed.
• Keep the HTTP timeout appropriate for your authentication UX.
• Avoid unnecessary retries.
• Monitor Autheona API usage and rate limits.
• Avoid storing the full Autheona intelligence response in Auth0 metadata unless required.
• Revoke and replace an Autheona access token immediately if it is exposed.

Minimal Integration Architecture

For registration protection:

flowchart TD
  A[User] --> B[Auth0 Registration]
  B --> C[Pre User Registration Action]
  C --> D[Autheona User Trust API]
  D --> E{Policy Decision}
  E -->|allow| F[Create Auth0 user]
  E -->|ignore| G[Continue registration]
  E -->|block| H[Deny registration]

For login protection:

flowchart TD
  A[User] --> B[Auth0 Login]
  B --> C[Post Login Action]
  C --> D[Autheona User Trust API]
  D --> E{Policy Decision}
  E -->|allow| F[Continue login]
  E -->|ignore| F
  E -->|block| G[Deny login]

Support and Documentation

• Autheona Quick Start
• Autheona Access Tokens
• Autheona API Reference
• Autheona User Trust API
• Autheona Policy Editor
• Auth0 Actions Documentation
• Auth0 Pre User Registration Actions
• Auth0 Post Login Actions