OIDC Integration Guide

Overview

This guide shows you how to integrate Hopae Connect with the standard OpenID Connect (OIDC) Authorization Code flow. You will redirect users to the Hopae OpenID Provider (issuer: https://connect.hopae.com), receive an authorization code on your redirect URI, and exchange it for tokens using the OIDC token endpoint. For a shorter walkthrough, start with the Quickstart Guide.

How It Works

Console Configuration

Redirect URI Management

Configure your redirect URIs in the Hopae Console:

Open your application in the Console.
Navigate to Developer settings and add each redirect URI you expect to use (production, staging, mobile deep links, etc.).

Authorization Request Construction

Use the /auth endpoint on the issuer domain (https://sandbox.connect.hopae.com/auth for sandbox, https://connect.hopae.com/auth for production):

const authorizationEndpoint = "https://sandbox.connect.hopae.com/auth"; // Sandbox
const redirectUri = "https://localhost:3000/callback";

const params = new URLSearchParams({
  client_id: "YOUR_CLIENT_ID",
  redirect_uri: redirectUri,
  response_type: "code",
  scope: "openid idv",
});

const authorizationUrl = `${authorizationEndpoint}?${params.toString()}`;

Authorization Request Parameters

Parameter	Required	Description	Example
`client_id`	Yes	Your Hopae Connect client identifier	`5SZdu0fn`
`response_type`	Yes	Must be `code`	`code`
`redirect_uri`	Yes	Whitelisted callback URI	`https://localhost:3000/callback`
`scope`	Yes	Include `openid`; add `idv` to receive normalized identity data	`openid idv`
`nonce`	Recommended	Replay protection for ID tokens (especially browser-based clients)	`4d9961bd-12a9-46d0-803f-aafef1bf814d`
`prompt`	Optional	Force a specific UX path (`login`, `consent`, `select_account`)	`login`
`acr_values`	Optional	Request verification constraints. See format below	`urn:hopae:loa:3`

acr_values Format

The acr_values parameter accepts space-separated URN values to control verification:

URN Type	Format	Description
LoA	`urn:hopae:loa:{level}`	Request minimum Level of Assurance (1–5)
Provider	`urn:hopae:id:{providerId}`	Filter to specific identity providers

Examples:

# Request minimum LoA 3
acr_values=urn:hopae:loa:3

# Filter to specific provider
acr_values=urn:hopae:id:bankidse

# Combine LoA and provider
acr_values=urn:hopae:loa:3 urn:hopae:id:mitid

# Multiple providers (comma-separated)
acr_values=urn:hopae:id:mitid,bankidse

Callback Handling

After the user completes verification, Hopae redirects to your redirect_uri with either an authorization code or an error. Success Response:

https://localhost:3000/callback?code=auth_abc123&state=b2a6c120-8d07-4f8f-a54f-ff832c3772b3

Error Response:

https://localhost:3000/callback?error=access_denied&error_description=User%20cancelled&state=b2a6c120-8d07-4f8f-a54f-ff832c3772b3

Validate the state value before proceeding.

Token Exchange

Exchange the authorization code for tokens using the OIDC /token endpoint.

curl -X POST https://sandbox.connect.hopae.com/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=auth_abc123&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback"

const response = await fetch("https://sandbox.connect.hopae.com/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    Authorization: "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`),
  },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: authCode,
    redirect_uri: redirectUri,
  }),
});

const { access_token, id_token } = await response.json();

import requests
from base64 import b64encode

credentials = b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()

response = requests.post(
    'https://sandbox.connect.hopae.com/token',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    data={
        'grant_type': 'authorization_code',
        'code': auth_code,
        'redirect_uri': redirect_uri,
    }
)

token_response = response.json()
id_token = token_response['id_token']

ID Token Claims

Wondering what data you’ll get back? See the Return Data Model for normalized claims, assurance, issuers, presentation, and evidence. Explore the Return Data Model →

Mobile Integration

You can initiate the OIDC flow from native apps using platform browser sessions (ASWebAuthenticationSession, Custom Tabs, etc.). The Expo example below demonstrates the pattern:

import * as AuthSession from "expo-auth-session";

const issuer = "https://sandbox.connect.hopae.com";

export async function startVerification() {
  const discovery = await AuthSession.fetchDiscoveryAsync(issuer);
  const redirectUri = AuthSession.makeRedirectUri({ useProxy: false });

  const authRequest = new AuthSession.AuthRequest({
    clientId: CLIENT_ID,
    redirectUri,
    responseType: AuthSession.ResponseType.Code,
    scopes: ["openid", "profile"],
    usePKCE: false,
  });

  const result = await authRequest.promptAsync(discovery);

  if (result.type === "success" && authRequest.code) {
    // Exchange authRequest.code on your secure backend with /token
  }
}

On iOS, AuthSession uses ASWebAuthenticationSession; on Android it launches a Custom Tab. This keeps user credentials within trusted system components while preserving the OIDC redirect semantics.

Common Issues and Solutions

invalid_redirect_uri

Ensure the URI is listed in your Console allow list (exact match).
URL-encode the value when placing it on the query string.
Confirm you’re using the correct environment (sandbox vs production).

invalid_grant

Authorization codes expire in 5 minutes and are single-use.
Confirm you are targeting the correct issuer when exchanging the code.

State or nonce validation failures

Persist the generated values securely between request and callback.
Reject callbacks where state or nonce is missing or mismatched.
Log mismatches (without sensitive data) for investigation.

Next Steps

API Integration

Build custom verification experiences with direct API calls

Verification Flow

Understand every step in the verification lifecycle

Getting Started

Integrations

Concepts

Data Types

Security

OIDC Integration Guide

Overview

How It Works

Console Configuration

Redirect URI Management

Authorization Request Construction

Authorization Request Parameters

acr_values Format

Callback Handling

Token Exchange

ID Token Claims

Mobile Integration

Common Issues and Solutions

Next Steps

API Integration

Verification Flow

​Overview

​How It Works

​Console Configuration

​Redirect URI Management

​Authorization Request Construction

​Authorization Request Parameters

​acr_values Format

​Callback Handling

​Token Exchange

​ID Token Claims

​Mobile Integration

​Common Issues and Solutions

​Next Steps

API Integration

Verification Flow

Overview

How It Works

Console Configuration

Redirect URI Management

Authorization Request Construction

Authorization Request Parameters

acr_values Format

Callback Handling

Token Exchange

ID Token Claims

Mobile Integration

Common Issues and Solutions

Next Steps