Check + Human Interest Integration Guide

Introduction

Human Interest is an online platform that helps small businesses purchase 401(k) plans.

The Check + Human Interest integration enables any partner to offer a 401(k) plan purchasing experience directly in their platform. End users can either connect to an existing Human Interest plan or create a new one through a guided onboarding flow.

🚧

Implementation Timeline Expectations

In order to test the Accrue component, Check requires additional information. Additionally, in order to launch the Accrue component in production, you may need to sign a contract amendment.

This implementation process may take up to 2 weeks to complete. It will take Accrue up to 5 business days to allowlist the URLs where you are hosting the component.

If interested in using our component, please reach out to your Check representative to get this implementation process started.

Quick Start Checklist

• Obtain your Check Partner ID and API credentials
• Generate a shared secret for each environment (dev + production)
• Securely share secrets with Human Interest
• Implement the authorization endpoint call
• Implement the JWT generation and redirect
• Build the UI for users to initiate the connection
• Test in development environment with Human Interest

Prerequisites

Before implementing this integration, ensure you have:

• A Check partner account with API access
• Familiarity with Check's OAuth flow
• A secure secrets management solution (e.g., AWS Secrets Manager, HashiCorp Vault)
• Access to a development/sandbox environment for testing
• A signed contract with Human Interest

Overview

The diagram below provides a high level overview of the auth process between the Check Partner, Check, and Human Interest.

Step 1: Generate Your Shared Secret

Generate a secure, 32-byte (256-bit), base64-encoded secret that will be used to sign JWTs sent to Human Interest.

const crypto = require('crypto');

const secret = crypto.randomBytes(32).toString('base64');
console.log(secret);

❗️

Important:

• Generate one secret per environment (development and production)
• Store secrets securely using a tool like AWS Secrets Manager—do not commit to version control
• Share secrets with Human Interest through a secure channel (not Slack or plaintext email)

Step 2: Build the User Interface

Create or update a page that allows users to initiate a connection to Human Interest. This page should:

1. Contain a clear UI element (e.g., button) indicating the user will connect to Human Interest
2. Be capable of receiving redirects from Human Interest (to support existing HI users initiating connections from within Human Interest)

Example button text: "Connect to Human Interest" or "Set up 401(k) with Human Interest"

Step 3: Authorize the Integration

When a user initiates the connection, make a request to Check's API to authorize the integration.

3a. Create an OAuth access token

Follow Check's instructions for creating an OAuth access token.

3b. Authorize the integration partner

Call the authorize integration partner endpoint with:

Step 4: Generate the JWT

After receiving a successful response from Check, generate a signed JWT for the redirect to Human Interest.

Payload requirements

Token requirements

• Algorithm: HS256
• Expiration: 1 hour
• Signed with: Your shared secret

import * as jwt from 'jsonwebtoken';
import { SHARED_SECRET } from '@src/config';

const PARTNER_ID = 'pro_123';
const COMPANY_ID = 'com_456';

/**
 * Creates an HMAC-SHA256 signed JWT token for Human Interest redirect.
 */
function createPartnerSignedToken(
  secret: string,
  partnerId: string,
  companyId: string
): string {
  const payload = {
    check_company_id: companyId,
    check_partner_id: partnerId,
  };

  const options: jwt.SignOptions = {
    algorithm: 'HS256',
    expiresIn: '1h',
  };

  return jwt.sign(payload, secret, options);
}

const token = createPartnerSignedToken(SHARED_SECRET, PARTNER_ID, COMPANY_ID);

Step 5: Redirect to Human Interest

Redirect the user to Human Interest with the signed JWT appended to the URL.

Replace {token} with the JWT generated in Step 4.

User Experience After Redirect

Once redirected to Human Interest, users will:

1. Existing HI users: Select their plan/division and finalize the connection
2. New HI users: Complete a self-service onboarding flow to create a new 401(k) plan

No special handling is required on your end to distinguish between these user types.

Testing

To test the integration:

1. Provide Human Interest with access to your development or sandbox environment
2. Human Interest cannot provide external access to their dev environment at this time
3. Test both new user and existing user flows

import * as jwt from 'jsonwebtoken';
import { SHARED_SECRET } from '@src/config';

// --- Configuration ---
const PARTNER_ID = 'pro_123'; 
const COMPANY_ID = 'com_456';

/**
 * Creates an HMAC-SHA256 signed JWT token using standard claims.
 */
function createPartnerSignedToken(secret: string, partnerId: string, companyId: string): string {
  // 1. Define the Payload (Custom Claims Only)
	const payload = {
  	check_company_id: companyId,
    check_partner_id: partnerId,
 	};

  // 2. Define the Options (Header and Standard Claims)
  const options: jwt.SignOptions = {
    algorithm: 'HS256',
    // Library automatically sets 'iat' (issued at) to current time.
    // Library automatically calculates 'exp' (expiration) based on this setting:
    expiresIn: '1h', // Example: Token expires 1 hour from now.
  };

  // 3. Sign the token
  const token = jwt.sign(payload, secret, options);

  return token;
}

createPartnerSignedToken(SHARED_SECRET, PARTNER_ID, COMPANY_ID);

FAQ

Q: Is there any difference in the flow for a user with an existing Human Interest account?

A: On your end, no. You may receive a redirect from Human Interest when an existing user attempts to connect to your service, but no special handling is required.

Q: What happens after our user connects to Human Interest?

A: After you redirect to Human Interest, the user will land on a page where they are given the option to connect to an existing Human Interest plan or create a new one. Existing HI users can select their plan/division and finalize the connection. New HI users will be taken through our self-service onboarding flow to create a plan.

Q: How do we test the integration?

A: You should provide Human Interest access to a dev or sandbox environment to test. We can not provide external access to our dev environment at this time.

Support

Additional questions? Reach out to:

• Check: [email protected]
• Human Interest: [email protected]