The Interac Hub is an HTTP API which simplifies ID verification. It conforms to the OAuth 2.0 and OpenID Connect specifications for authorization code grant flow and features three simple HTTP endpoints. These endpoints can be invoked via most standard libraries from your programming language of choice, OAuth-compatible third-party libraries, or common tools such as curl and Postman. Data is returned in the popular JSON format.

This is a quick walkthrough of what it takes to perform an initial integration with the Interac Hub API. For in-depth details, refer to the Integration Guide and Appendices.

A four-step example based on Python is also available in the Recipes section.

1. Collect Onboarding/Integration Details

We'll need a few pieces of information prior to API integration. This will be provided by your client representative during the onboarding process.

OIDC Client ID: Unique ID used when making Hub API requests
OIDC Scope: Specifies which user claims and what Interac Hub flows (IVS vs. IDVS) are available
OIDC well-known URL: Endpoint containing JSON metadata on all Hub API endpoints

Additionally, on the integrating partner side a few URLs will need to be prepared to support this integration:

Redirect URL: One or more URLs to redirect the user back to the partner after ID verification
JWKS URL: A public URL hosting the public signing key of the partner in JWK format. This is an RSA signing key using the RS256 algorithm

There are no restrictions on how you prepare these URLs. These can be created and hosted from a backend service using a framework such as Node.js, Flask, Spring Boot or other alternatives.

Refer to the Client Onboarding process for more details.

2. Obtain Interac Hub API Endpoints

To call the Interac Hub API OIDC endpoints, these can be parsed from the OIDC well-known URL which returns a JSON response with metadata on the endpoint URLs.

Refer to API Endpoints for how to query this well-known endpoint.

The endpoint can be accessed via a standard HTTP GET request such as:

curl https://gateway-devportal2.pp.vids.dev/.well-known/openid-configuration

The JSON metadata returned contains the endpoints for the subsequent authorization or PAR, token, and userinfo endpoints which conform to OIDC.

{
    "authorization_endpoint": "https://gateway-devportal2.pp.vids.dev/auth",
    "token_endpoint": "https://gateway-devportal2.pp.vids.dev/oauth2/token",
    "userinfo_endpoint": "https://gateway-devportal2.pp.vids.dev/userinfo",
    "pushed_authorization_request_endpoint": "https://gateway-devportal2.pp.vids.dev/auth/par"
}

3. Initial Hub API Authorization Call

To start user ID verification, place an initial call to the authorization endpoint via GET /auth of the Interac Hub API. This is a GET request and you can initiate this by building a URL to redirect the user to.

Refer to Authorization Endpoint on how to build this URL.

The constructed URL to redirect the user to looks like the below. A user following this URL will be redirected to the Interac Hub landing page where ID verification can be performed through a series of screens shown in the web browser.

https://gateway-devportal2.pp.vids.dev/auth?request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNJbERlUjhENFJleHJabVVkS2hCeE1zRDJiTVg0bDg3XzVKckFSaDRWSVUifQ.eyJhdWQiOiJodHRwczovL2dhdGV3YXktZGV2cG9ydGFsMi5wcC52aWRzLmRldi8iLCJjbGllbnRfaWQiOiJodWItaW50LXRlYW0iLCJjb2RlX2NoYWxsZW5nZSI6ImF1TEtIVTNpWVlBcHlDeDdXUVU5Q195RVdWeXM1cTJEMUozQjZwaFYxTXMiLCJjb2RlX2NoYWxsZW5nZV9tZXRob2QiOiJTMjU2IiwiaXNzIjoiaHViLWludC10ZWFtIiwibm9uY2UiOiJhYmRkNWVlZDg5ODM0YjYyYWVlMmRlN2E2ZWQ0ZDkyZSIsInJlZGlyZWN0X3VyaSI6Imh0dHA6Ly9sb2NhbGhvc3Q6NTAwMC9sb2dpblJlc3BvbnNlIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJzY29wZSI6Im9wZW5pZCBvbmx5Vm1lIiwic3RhdGUiOiI1ZGU3ODk4ODFjYzk0NGE3OGU5YzFjOWQ5NDdmNzg2NyIsInVpX2xvY2FsZSI6ImVuLUNBIn0.rBmjM6KEYsoBCoR2Wk3XnAP57AVqVo-gG4BdQp1wVZs4GiD77Oo9JTYvOZXyk1qmdttxkMUUo8Uj5ibAmsV0kY4-56mdAOuLryBYVRpwmVAWIgJ7I49LItNDnRbOhSyJkUsXUUFu85am27r83XoTjm5xIHYzfFCsNoBVD0oDsuFDZX8ri6UY7vK3Y9feIBqPYXERmuBsDohwogyZbXEUe0AbHFmdcYyYVcLY5q1mSF_0VBqZIsRiC73sipohhGkWy0No-oArTshKZ5C_BWxpCoTxCiS8xvz6wffmyJBqKbOjPYKmRD59BZ6yRysXzbShsFaezw_MwsRaMWfFMnrT3A&response_type=code&client_id=hub-int-team&scope=openid+onlyVme&state=5de789881cc944a78e9c1c9d947f7867&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2FloginResponse

After completing ID verification on the Interac Hub, the user will be redirected back to the partner via a redirect URL with query parameters similar to this:

http://my.partner.website.io/loginResponse?code=5GT81abUDETEOpVegWBZ78AejqElS-atMzTNF_7UQYQ.IfKMxHcxM5PdoDtQyNhXl5jb8uS5lxs1xc-hQHRcR8Q&scope=openid+onlyVme&state=5de789881cc944a78e9c1c9d947f7867

Alternatively, if you decide to use a back-channel server to server PAR request via POST /auth/par, refer to Pushed Authorization Request on how to initiate an API request and use the response to redirect the user to.

4. Obtain Hub API Token

Upon successful user ID verification, a one-time authorization code is returned back to the partner via a partner redirect URL. Note that the code is returned in the code query parameter during the redirect.

http://my.partner.website.io/loginResponse?code=5GT81abUDETEOpVegWBZ78AejqElS-atMzTNF_7UQYQ.IfKMxHcxM5PdoDtQyNhXl5jb8uS5lxs1xc-hQHRcR8Q&scope=openid+onlyVme&state=5de789881cc944a78e9c1c9d947f7867

Using this authorization call, submit a POST /oauth2/token request to obtain an access_token.

Refer to Token Endpoint on how to submit this API request.

An example of this POST request looks like this:

curl -X 'POST' \
'https://https://gateway-devportal2.pp.vids.dev/oauth2/token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&code=5GT81abUDETEOpVegWBZ78AejqElS-atMzTNF_7UQYQ.IfKMxHcxM5PdoDtQyNhXl5jb8uS5lxs1xc-hQHRcR8Q&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNJbERlUjhENFJleHJabVVkS2hCeE1zRDJiTVg0bDg3XzVKckFSaDRWSVUifQ.eyJhdWQiOiJodHRwczovL2dhdGV3YXktZGV2cG9ydGFsMi5wcC52aWRzLmRldi9vYXV0aDIvdG9rZW4iLCJleHAiOjE2NzU5NzI4ODQuNDU3MDM4LCJpYXQiOjE2NzU5NzI1ODQuNDU3MDM4LCJpc3MiOiJodWItaW50LXRlYW0iLCJqdGkiOiIzNWE1YmFlNDlhODM0ZWI2ODRjOGM4OGVmNzE5MDQ3NSIsInN1YiI6Imh1Yi1pbnQtdGVhbSJ9.QL169STxXxL4-Cpxokmf5C1KNAXgfJyjLa5rnrrpLnhpPdpelT_IUt1oaZ1itTFDtYhFjx1tBzBJULkNVncAX0EDCLUT_lLVGBX5bx_uSKPcJm9YOJI3HCgVYU3r_JvFiQbzr-mvWrMkvuFr8hOevu3nCNMwN3MlfWZ1t-ymgLnwy7dteN7v1MakUhDSxWY7tCIW0kJPMPfJzN8ciCBW-iJq-GZYyPF0n9t3ulHVuFxBNYQReYD0amektL4Iy5f_NqgivYIjYNKgDxTZwpKocK2BfVx2jqvGi___-y21FDos15nMLI76Sk_Bt3K_hPQc6eSDDiFWZ9_spWkKMUs5bA&client_id=hub-int-team&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2FloginResponse&code_verifier=lFDBK1ByvwTCqM2hxrGVVWcLVvjKkIeTE1JZ4ms_ZhDxPiiA7qt0YWBh8qi9_j1n7WM2-QairlqSoPWKjFEruthLJWI5gvyWIpe7bQyeMo95FE8pK0jOvs40_N6pOq-Z'

And the accompanying JSON response with the access token looks like:

{
    "access_token": "ILcyQprq2MDuC9oxmiRDP0x1v7pvYh1UzhjuAB0nsyg.cfChPkBMaNxVWSQgSkauyRYgQrZTJ1skshsAWGr9Qds",
    "expires_in": 1800,
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzo3N2U5MDEzNS00YTM1LTRkMmYtYTIwMi1mOTE5MzY2YTc5ZDYiLCJ0eXAiOiJKV1QifQ.eyJhdF9oYXNoIjoiblVVWFZtRTZaM2dvS2ZQUF9DTk05USIsImF1ZCI6WyJodWItaW50LXRlYW0iXSwiYXV0aF90aW1lIjoxNjc1OTcyNTE0LCJjbGllbnRfaWQiOiJodWItaW50LXRlYW0iLCJleHAiOjE2NzU5NzYxODUsImZsb3ciOiJWTUVfT05MWSIsImlhdCI6MTY3NTk3MjU4NSwiaXNzIjoiaHR0cHM6Ly9nYXRld2F5LnByZXByb2QuaHViLXZlcmlmeS5pbnRlcmFjLWlkLmNhLyIsImpvYl9pZCI6ImE1OGE5YWQxLWM2NzgtNDM5YS1iN2IzLTkxOGVjZDFjNWE4YSIsImp0aSI6IjQzY2JlZDdjLTgzZTItNDc1MC05ZDZkLTUyYTFjMzU3OTRmMSIsIm5vbmNlIjoiMDk1MzMzMTdmNDhjNDgzODk4NDFhZmRhY2M2NDU1Y2YiLCJyYXQiOjE2NzU5NzI0NzAsInNjb3BlIjoib25seVZtZSIsInNpZCI6IjVlYzVlOTY3LWZjYzctNDBkYi1iOGY1LWRhNTBiMTRmMmUzNiIsInN1YiI6ImE1OGE5YWQxLWM2NzgtNDM5YS1iN2IzLTkxOGVjZDFjNWE4YSJ9.rUtZqbpx1v-HgcbSdqRBkJfHpJrjJgXJ9N61Nk4Sg9IW2ftWcA1LONSoC_eYWnfci06LeKxD_WCNtKod1wkAggnIOWoRO3y05xlDJuIKezGI0vikSdVjgJD34myt52thInThRsceveVJrtFx8IFqivQy7UMJ1qsLUwGfDFMOjL2e6aaG1uvjn_GnN7fYGw1cpajj-favHC_eUp5zUGcTZT6GFC1TxY21yS4C6e_6zotmeWFiTYHZszkkSOG8rle1DxqiVnoQ5lUgA1OeWWc5wEZXD3ElH-9aheQlxrowu0vLZaSlbEs3tHWX6ECvf5kRjgMJjO6JsXBSfbekkuYexX1FVxHi46T7HamObRVJkJaKbQVOSwbJV4Hy7YrBP5hS6sxkRYL6SXspnwmu6J0V4EUlQqlouamFP7GftIpHowWbyTi-WOuU4C1wGA-B-EV7Ll57velDMimrVJ0as7Zu0eT94Jc1TGsaSNy1l9GuNk60hPmA-uGyO3Lz-4MZuYv2bVDRiwHUQV6MJU1TrXejZUW5hshfiA1RyD5HYXIenDW06zDW0DbKx9OWbUg44B9WQfV5h-p1wse1zEaXqP2jdK-NXb_ScbcJV2_J4icdgh4oAW0tPTeGZGSfekZpnvdzGM1kz-EE4TB62BYFmT3gS0uhpy3nY69oxx8YzYm2zp0",
    "scope": "openid onlyVme",
    "token_type": "bearer"
}

5. Obtain User Claims

Finally, initiate a GET /userinfo to the userinfo endpoint using the provided access token to obtain the user claims. This applies to both the Interac Verification Service (IVS) using financial institution authentication and Interac Document Verification Service (IDVS) using government document verification.

Refer to UserInfo Endpoint for granular steps.

An example GET request with the access token in the header looks like this:

curl 'https://gateway-devportal2.pp.vids.dev/userinfo' \
--header 'Authorization: Bearer ILcyQprq2MDuC9oxmiRDP0x1v7pvYh1UzhjuAB0nsyg.cfChPkBMaNxVWSQgSkauyRYgQrZTJ1skshsAWGr9Qds'

Depending on whether the user went through IVS (financial institution authentication) or IDVS (government document verification), the resulting JSON response looks like:

{
    "source": "bank",
    "sub": "78d41cff-678e-4a3e-9482-afa43ceae222",
    "com.securekey.verified.me.license_id": "9h8EGxUHCMQm3GRRHMKho0ch7UMC25cuUwn69suwj1M",
    "com.securekey.verified.me.ui_locale": "en-CA",
    "address": {
        "country": "CA",
        "locality": "Toronto",
        "postal_code": "M2P 1N6",
        "region": "ON",
        "street_address": "4101 Yonge Street"
    },
    "birthdate": "1965-03-03",
    "email": "[email protected]",
    "family_name": "Doe",
    "given_name": "John",
    "middle_name": "M",
    "phone_number": "14169378708"
}

{
    "source": "driving_licence",
    "sub": "cd9a9bab29f26b5c9576e2387f5785372f26afe143c0bbc635089db7bba2a212",
    "com.securekey.verified.me.ui_locale": "en-CA",
    "com.securekey.vids.job_id": "d306f935-cb23-4a39-8acc-232eed539e1e",
    "address": {
        "country": "CA",
        "locality": "Atlanta",
        "postal_code": "S3B 8X2",
        "region": "South Dakota",
        "street_address": "714 Shoals haven"
     },
     "birthdate": "1989-06-06",
     "family_name": "Rodriguez",
     "given_name": "Rasheed",
     "issue_date": "2018-07-26",
     "issuing_authority": "South Dakota",
     "issuing_country": "CA",
     "nationality": "N/A",
     "scan_result": "CLEAR",
     "doc_number": "N9462260754",
     "doc_type": "drivers_license",
     "expiry_date": "2025-12-07"
}

From here, you can parse this response and allow the user to proceed with their user journey!