Skip to main content
Version: 11.3.0

Extending HYPR Affirm with Code Customizations

This playbook is the running order for adding custom code to a HYPR Affirm verification flow. Each step says what you decide or do, then links to the page that describes it in detail. Follow the link, complete the step, and come back here for the next one.

Who this is for: developers and administrators who need a verification flow to read profile data from a system other than Okta or Entra ID, to act on a verification decision in an external system, or to send notifications through their own gateway.

Before you start: you need a verification flow you can edit, and access to HYPR Affirm → Advanced Settings → Code Customizations in Control Center.

Confirm You Need a Customization​

Reach for custom code only where the standard integrations fall short.

What you'll decide:

  • Whether your identity provider already supplies every profile field your flow requires
  • Whether your system of record keys users on an identifier that needs mapping
  • Whether the verification decision must drive an action in another system

Go to Choose a customization type →

If a standard integration covers you, stop here. You do not need a customization.

Decide Which Verification Steps the Flow Uses​

The steps you choose determine which profile fields the flow needs, which in turn determines what a User Directory customization has to return.

What you'll decide:

  • Which steps meet your assurance requirement
  • Which profile fields those steps compare against
  • Whether your system of record actually holds those fields

Go to Profile data each step requires →

For the wider flow-design decisions around this (the identifier users type on the first screen, outcomes and branding), see Identity Verification and Assurance Strategies.

Pick the Customization Type​

Each type has its own input and output contract. Pick the one that matches the job before you write anything, using the following table.

If you need to…Use
Read the user profile from your own systemUser Directory
Act on the verification decision in another systemOutcome API Call
Send SMS through your own gatewaySMS Sending and SMS Verifying
Send email through your own gatewayEmail
Write verification images to an external directoryImage Writeback
Insert your own verification step into the flowCustom Verification Step

Go to the full contract reference →

Register the Customization and Its Attributes​

Create the customization in Control Center first, so you have somewhere to put the code and the environment values it reads.

What you'll do:

  • Create the customization and choose its type
  • Add the attributes your script reads, such as API URLs, tenant identifiers and credentials
  • Save

Keep environment values in attributes rather than in the script, so the same customization can move between environments unchanged.

Go to Create a Customization →

Write the Script​

The script runs in an ES2022 runtime with no browser or Node.js APIs, so every call to the outside world goes through the ctx object.

What you'll learn:

  • The handle entry point and how the input arrives
  • The ctx object: HTTP methods, JWT helpers, hashing and the short-lived value store
  • The design pattern for your customization type
  • A worked User Directory customization, built up in stages

Go to Writing Affirm Code Customizations →

Jump straight to a part: the entry point · the ctx object · design patterns · worked example

Decide What the Script Returns When It Cannot Finish​

How you signal a missing record or an unreachable API is part of the design, not an afterthought. An uncaught exception is not a controlled failure signal.

What you'll learn:

  • What to return when the record is not found
  • How to surface your own error condition
  • What the flow does when the script throws

Go to Handling errors →

Test Before You Attach It to a Live Flow​

Test mode runs the script against values you supply and shows its logs, including any error, so you can fix problems before a live flow uses it.

What you'll do:

  • Turn on Edit Mode to change code or attributes, then switch to Test
  • Exercise every outcome the flow can produce, approved and denied
  • Confirm every attribute your code reads is configured, with names matching exactly

Go to Edit and test a customization →

For end-to-end validation of the whole deployment, see Affirm Test Cases.

Attach the Customization to a Verification Flow​

A registered customization does nothing until a flow uses it. Assignment happens in the flow's Advanced Customization settings, not on the customization itself.

What you'll do:

  • Open the verification flow and, under Advanced Customization, the section the customization belongs to: User Directory, Image Directory, Email, SMS or Outcome
  • Select your customization from that section's drop-down
  • Save the flow

Go to Configure Verification Steps →

For a worked assignment example, see Liveness-Only (Anchor Image).

Confirm It in Production​

Customization results are recorded as part of the verification flow, so you can confirm behavior without instrumenting anything yourself.

Where to look:

  • Activity Log — the customization's result alongside the flow's other step results
  • Affirm Helpdesk — the same history for service-desk operators
  • Audit Trail — the verification flow configuration change when you assign the customization to a flow, and writeback events for an Image Writeback customization. Edits to the customization's code and attributes are not recorded there.

These are not part of the main sequence. Come back to them if your deployment needs them.