The partner can now retrieve the user claims applicable for its OIDC scope by using the access_token in the previous step. The RP performs a HTTP GET request to the Hub's userinfo_endpoint. The returned user claims are in JSON format.

GET /userinfo HTTP/1.1
Host: hub_server.example.com
Authorization: Bearer <access_token>

Back Channel Request: This is an OAuth back channel request, performed via the RP's backend server to the Hub's server.

Securing user claims: An RP/DAC must perform this request in the back channel, away from the user agent/browser. The user claims returned contains personally-identifiable information (PII) and must be protected by the RP/DAC.

Important: Refer to Data Retention on details regarding storage of user claims in accordance with the mandated data retention policy.

Referenced Standard(s): RFC 6749: The OAuth 2.0 Authorization Framework (4.1.3 Access Token Request), RFC 7521 Assertion Framework for OAuth 2.0

Example Request / Response

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

The user claims are returned as JSON. These user claims are determined by the OIDC scope and digital asset bundles/user claims defined during onboarding. For the exact user claims returned, refer to the digital asset definition bundle schema provided by the Integration team.

Below are illustrative examples of the user claims returned for different flows and typical formatting.

Interac Verification Service (e.g. openid onlyVme_scope)

This scope returns user claims resulting from a successful financial institution online authentication. The claims returned reflect what is on file for that user with their financial institution.

Different digital asset bundles (i.e user claims) can be subscribed to depending on the partner agreement and can be referenced Published DA (internal KB, access restricted).

{
    "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"
}

Interac Document Verification Service (e.g. openid document_scope)

This scope returns user claims resulting from a successful validation of the user's government document and live biometric selfie.

There are a number of supported government documents indicated in the source field. Additionally, the scan_result shows whether the document was deemed valid or invalid along with optional fields indicating any problems with the documents/selfies.

Full details can be found in the Appendices: Pre-configured Scopes in the section openid document_scope.

{
    "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"
}

Interac Verification Service AND Document Verification Service (e.g. openid dual_scope)

This scope combines IVS (financial institution online authentication) and IDVS (government document verification) and forces the user to use both. As a result, the user claims returned is a combination of IVS and IDVS with a matching object indicating whether the user's government document details matched what's on file with their financial institution.

{
    "com.securekey.matching": {
        "identityData": {
            "leftDigitalIdentity": "com.securekey.verified.me",
            "rightDigitalIdentity": "com.securekey.vids"
        },
        "matchData": {
            "birthdate_score": 100,
            "family_name_score": 100,
            "given_name_score": 100,
            "matchScore": 100,
            "matchThreshold": 65
        },
        "matchStatus": "CLEAR"
    },
    "com.securekey.verified.me": {
        "address": {
            "country": "CA",
            "locality": "Atlanta",
            "postal_code": "S3B 8X2",
            "region": "South Dakota",
            "street_address": "714 Shoals haven"
        },
        "birthdate": "1989-06-06",
        "dacPseudonym": "a6zTtvwmOSFnNf7XOyiKOcc5L34s_Y6LyvGce0pHQFo",
        "email": "[email protected]",
        "family_name": "Rodriguez",
        "given_name": "Rasheed",
        "license_id": "KE1JkDHj4BllfLfKjSVfCmMNbhEaHBhw80RjwhPnYUs",
        "middle_name": "Orlando",
        "phone_number": "1208575388",
        "source": "bank",
        "sub": "a6zTtvwmOSFnNf7XOyiKOcc5L34s_Y6LyvGce0pHQFo",
        "ui_locale": "en-CA"
    },
    "com.securekey.vids": {
        "address": {
            "country": "CA",
            "locality": "Atlanta",
            "postal_code": "S3B 8X2",
            "region": "South Dakota",
            "street_address": "714 Shoals haven"
        },
        "birthdate": "1989-06-06",
        "com.securekey.verified.me.ui_locale": "en-CA",
        "doc_number": "N9462260754",
        "doc_type": "drivers_license",
        "expiry_date": "2025-12-07",
        "family_name": "Rodriguez",
        "given_name": "Rasheed",
        "issue_date": "2018-07-26",
        "issuing_authority": "South Dakota",
        "issuing_country": "CA",
        "jobId": "ab7b1fbf-f5f0-4858-ac22-f82e90970dc7",
        "scan_result": "CLEAR",
        "source": "driving_licence",
        "sub": "ab7b1fbf-f5f0-4858-ac22-f82e90970dc7"
    },
    "birthdate": "1989-06-06",
    "family_name": "Rodriguez",
    "given_name": "Rasheed",
    "sub": "d38ac3700cceba95f045c60b07eb39cfe38148f9a6fe55b70ab81da88778020a"
}

Interac Verification Service (with Subject Matching enabled)

The Interac Hub also has an internal service called Subject Matching, which allows a partner to send across the user's personal details (e.g. first name, last name, birthdate, phone number, etc.) and matches these details with either their financial institution details (using IVS) or what's on their government document (using IDVS).

A matching object provides the details of how well the partner's submitted user details matches with the user's financial institution/government document details.

{
    "com.securekey.matching": {
        "identityData": {
            "leftDigitalIdentity": "com.securekey.verified.me",
            "rightDigitalIdentity": "request.subject"
        },
        "matchData": {
            "birthdate_score": 100,
            "family_name_score": 100,
            "given_name_score": 100,
            "matchScore": 100,
            "matchThreshold": 65,
            "postal_code_score": 100
        },
        "matchStatus": "CLEAR"
    },
    "com.securekey.verified.me": {
        "address": {
            "country": "CA",
            "locality": "Toronto",
            "postal_code": "M2P 1N6",
            "region": "ON",
            "street_address": "4101 Yonge Street"
        },
        "birthdate": "1965-03-03",
        "dacPseudonym": "K_CsX_Yu4QXbwyA6vRjh6c9_v8Ot3CcqXgznmNbrFS8",
        "email": "[email protected]",
        "family_name": "Doe",
        "given_name": "John",
        "license_id": "I9IizVe-ZqdNn2lmdBu9b65sCpMFGH7RMKPVyJQ4vSs",
        "middle_name": "M",
        "phone_number": "14169378708",
        "source": "bank",
        "sub": "K_CsX_Yu4QXbwyA6vRjh6c9_v8Ot3CcqXgznmNbrFS8",
        "ui_locale": "en-CA"
    },
    "birthdate": "1965-03-03",
    "family_name": "Doe",
    "given_name": "John",
    "sub": "dda8cc55da8eb696136a6edfe03183a96662b4e2417eb7548ffc3bed9381c7d2"
}

If HidePII is enabled for the client ID's OIDC scope during onboarding, only the matching object is returned, with no user PII. The resulting response will look identical to the above with only the com.securekey.matching object returned.

{
    "com.securekey.matching": {
        "matchStatus": "CLEAR",
            "matchData": {
            "matchScore": 100,
            "matchThreshold": 65,
            "given_name_score": 100,
            "family_name_score": 100,
            "birthdate_score": 100,
            "postal_code_score": 100
        },
        "identityData": {
            "leftDigitalIdentity": "com.securekey.verified.me",
            "rightDigitalIdentity": "request.subject"
        }
    },
    "sub": "ToAafjHQlkL_r0841sTaXqcK_kX9fygn0vqpPsSgPCU"
}

Interac Verification Service (with Async Delivery enabled)

The Interac Hub has the capability to redirect the user back to the RP without having to wait for ID verification to complete on the Hub screen. This enables the user to continue their user journey on the RP side while waiting for processing that typically takes longer such as government ID + selfie verification on IDVS.

If asyncResultDelivery is enabled, the response will return the processing status, if not complete along with a retry-after value (in seconds) in the header for when the RP should send a subsequent request to the Userinfo endpoint.

{
    "state": "PROCESSING",
    "verifications": {
        "document": {
            "state": "DATA_PROCESSING"
        },
        "matching": {
            "state": "BLOCKED"
        }
    }
}

{
    "Date": "Wed, 22 Nov 2023 20:34:33 GMT",
    "Content-Type": "application/json; charset=utf-8",
    "Content-Length": "110",
    "Connection": "keep-alive",
    "retry-after": "10",
    "set-cookie": "SameSite=None",
    "cache-control": "no-store",
    "content-security-policy": "frame-ancestors 'none'",
    "x-frame-options": "SAMEORIGIN"
}