Affirm Content Customization API

The Affirm Content Customization API (introduced in HYPR 10.3.0) provides endpoints for managing content customizations used by Affirm Studio.

API-Only Implementation

This feature currently has API-only support. No Control Center user interface is available yet.

General Branding

For general branding customization (logos, backgrounds, colors), see Custom Branding.

Base URL

/content-customization

Authentication

All API endpoints require proper authentication. Include your API credentials in the request headers.

Endpoints

Create Content Customization

Creates a new content customization configuration.

POST /content-customization
Content-Type: application/json

Request Body:

{
  "displayName": "Content Customization 2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      },
      "cardContent": {
        "mainContent": "By proceeding, you agree to our verification process",
        "extraContent": "This process helps us verify your identity securely"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "accept": "I Accept",
        "decline": "Decline"
      }
    },
    "instructionsScreen": {
      "cardHeader": {
        "title": "Verification Instructions",
        "description": "Follow these steps to complete verification"
      },
      "cardContent": {
        "mainContent": "Please follow the instructions carefully to complete your verification",
        "extraContent": "Ensure you have a valid government-issued ID ready"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "continue": "Continue",
        "back": "Back"
      }
    }
  }
}

Response:

{
  "id": 123,
  "displayName": "Content Customization 2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      },
      "cardContent": {
        "mainContent": "By proceeding, you agree to our verification process",
        "extraContent": "This process helps us verify your identity securely"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "accept": "I Accept",
        "decline": "Decline"
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Update Content Customization

Updates an existing content customization configuration.

POST /content-customization/:content-customization-id
Content-Type: application/json

Request Body:

{
  "displayName": "Content Customization 2.2",
  "contentMap": {
    "instructionsScreen": {
      "cardHeader": {
        "title": "Updated Instructions"
      }
    }
  }
}

Response:

{
  "id": 123,
  "displayName": "Content Customization 2.2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      }
    },
    "instructionsScreen": {
      "cardHeader": {
        "title": "Updated Instructions"
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:45:00Z"
}

List All Content Customizations

Retrieves all content customizations.

GET /content-customization

Response:

{
  "contentCustomizations": [
    {
      "id": 123,
      "displayName": "Content Customization 2.2",
      "description": "Company-specific branding for verification screens",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:45:00Z"
    },
    {
      "id": 124,
      "displayName": "Spanish Localization",
      "description": "Spanish language content for global teams",
      "createdAt": "2024-01-16T09:15:00Z",
      "updatedAt": "2024-01-16T09:15:00Z"
    }
  ],
  "total": 2
}

Retrieve Specific Content Customization

Retrieves a specific content customization by ID.

GET /content-customization/:content-customization-id

Response:

{
  "id": 123,
  "displayName": "Content Customization 2.2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      },
      "cardContent": {
        "mainContent": "By proceeding, you agree to our verification process",
        "extraContent": "This process helps us verify your identity securely"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "accept": "I Accept",
        "decline": "Decline"
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:45:00Z"
}

Data Models

ContentCustomization

Field	Type	Description
id	Long	Unique identifier for the content customization
displayName	String	Display name for the customization
description	String	Description of the customization purpose
contentMap	AffirmContentMap	Screen-specific content configuration
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	Last update timestamp

AffirmContentMap

Contains configuration for all customizable screens:

Screen	Type	Description
consentScreen	BaseContentCustomizationMap	Initial consent screen
instructionsScreen	BaseContentCustomizationMap	Step-by-step guidance
loginIdentifierScreen	BaseContentCustomizationMap	Username/email input
phoneNumberOrEmailScreen	BaseContentCustomizationMap	Contact information collection
otpScreen	BaseContentCustomizationMap	One-time password verification
locationScreen	BaseContentCustomizationMap	Location-based verification
idvAwaitScreen	BaseContentCustomizationMap	Waiting for identity verification
idvRequestorReportScreen	BaseContentCustomizationMap	Verification status reporting
documentLivenessScreen	BaseContentCustomizationMap	Document and biometric verification
autoApprovalAwaitScreen	BaseContentCustomizationMap	Waiting for automatic approval
outcomeScreen	BaseContentCustomizationMap	Final verification results
deniedScreen	BaseContentCustomizationMap	Access denial notification

BaseContentCustomizationMap

Field	Type	Description
cardHeader	CardHeaderContentCustomizationMap	Header content configuration
cardContent	CardContentContentCustomizationMap	Main content configuration
cardFooter	CardFooterContentCustomizationMap	Footer content configuration
buttonLabels	Map<String, String>	Customizable button text

CardHeaderContentCustomizationMap

Field	Type	Description
title	String	Main screen title
description	String	Screen description text

CardContentContentCustomizationMap

Field	Type	Description
mainContent	String	Primary instructional text
extraContent	String	Additional information or tips

CardFooterContentCustomizationMap

Field	Type	Description
caption1	String	Primary footer text
caption2	String	Secondary footer text

JavaScript helper functions in Affirm code customizations

When you use Affirm code customizations (for example in Affirm Studio), the runtime exposes several helper functions for working with JWTs, HMACs, and hashes. These functions are available in the JavaScript context inside a customization and are primarily intended for advanced integrations, such as validating third‑party tokens or issuing signed payloads for downstream systems.

At a high level:

• jwtCreateSignedJwt(...)
  Creates and signs a JWT using the configured signing keys and options. Use this when you need Affirm to issue a signed token that another system can validate.

• jwtDecodeJwt(token)
  Decodes a JWT into header and payload without validating the signature. Use this for non‑sensitive inspection of token contents.

• jwtDecodeVerify(token, options) and jwtVerify(token, options)
  Decode and verify a JWT using the configured verification keys and validation rules. Use these to ensure a third‑party token is valid before allowing the user to proceed.

• sha256(value)
  Returns the SHA‑256 hash of the given value (string or bytes). Useful for generating deterministic identifiers or hashes that must match external systems.

• getHmacSHA256Signature(key, value)
  Computes an HMAC‑SHA256 signature of value using a secret key, for scenarios where you must sign data according to an external API’s requirements.

• base64EncodeToString(value)
  Encodes the given value as a Base64 string, for example when building HTTP headers or payloads for downstream APIs.

These helpers are available only inside the Affirm customization sandbox; they are not general‑purpose HYPR SDK methods. Use them in accordance with your organization’s security and key‑management policies (do not log secrets or expose them to end users).

Using environment variables in customization code

Affirm code customizations can also consume environment‑specific configuration so you do not have to hard‑code tenant‑specific values or secrets in JavaScript.

• Environment variables are defined per tenant / environment on the backend and are injected into the customization runtime at execution time.
• Common use cases include:
  • Issuer IDs or aud values for JWT verification.
  • API keys or endpoints for risk engines, case‑management, or notification systems.
• Environment variable values are not logged by default; avoid printing them to logs or rendering them on end‑user screens.

Contact HYPR Support or your HYPR representative for the exact provisioning and naming process for Affirm environment variables in your deployment.

Error Handling

The API returns standard HTTP status codes:

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Rate Limiting

API requests are subject to rate limiting. See the response headers for current rate limit information:

• X-RateLimit-Limit - Maximum requests per time window
• X-RateLimit-Remaining - Remaining requests in current window
• X-RateLimit-Reset - Time when the rate limit resets

Related Documentation

• Affirm Studio
• Affirm Installation and Configuration