Skip to main content

Get User

Describes the lightweight Get User call.

Purpose​

The purpose of the Get User is to provide a lightweight version of the bulkier Get Customer.

This endpoint is not directly correlated with the Consumer Data Standards APIs. See here for more information.

Data Adapter API​

Get User​

Loading...

 

Consumer Data Standards Associations​

The Get User call does not have direct correlation to the Consumer Data Standards APIs, instead it is utilised for a number of more abstract purposes as follows:

  • Userinfo Endpoint: Used to provide details regarding the user, notably name (name), first name (firstName), last name (lastName), when the record was last updated (updatedAt) and role (role) of the user in the context of the supplied principal.
  • ID Token Generation: Used to provide details regarding the user, notably name (name), first name (firstName), last name (lastName), when the record was last updated (updatedAt) and role (role) of the user in the context of the supplied principal.
  • Consent Flow: Used to identify vulnerability status (vulnerable) and also to provide details regarding the users access to customers they have a delegated Authority to Operate (authorityToOperate).

CDR Error Mapping​

TitleStatus CodeAdapter URN - Error CodeDetailCDR Status CodeCDR URN - Error Code
Legal Block451urn:dio:error:cds-all:Resource/LegalBlockThis status code indicates that the server is denying access to the resource as a consequence of a legal demand.400N/A - OAuth2 Error
Ineligible Block451urn:dio:error:cds-all:Resource/IneligibleBlockThis status code indicates that the Customer is ineligible for CDR Data Sharing.400N/A - OAuth2 Error
Call Center Block451urn:dio:error:cds-all:Resource/CallCenterBlockThis status code indicates that the consumer should call the Call Center for further information.400N/A - OAuth2 Error

 


Supplemental Fields​

The Get User call is a standalone call without a direct Consumer Data Standards endpoint.

Endpoint Specific Guidance​

The Get User call is a standalone call without a direct Consumer Data Standards endpoint.

As per the Minimum Requirements, it is compulsory that Get User is implemented.

The userId in the request body is the internal unique user id of the user in your systems. This is the userId of the user that authenticated to start the arrangement (returned from Verify Login). The principal is the entity being shared in the CDR (i.e., a person or a business) and is the identifier that is subsequently used in all adapter calls to represent the entity that we want to list accounts, payees, payments, etc for. We explicitly separate the concept of the user that authenticated from the entity being shared in the CDR because with Multi Party and Business Nominated Representatives it is important they are different.

With individually owned accounts, this concept does not make sense because if a person is sharing their account, they are sharing their own accounts so the user and the principal are usually the same thing - in fact many of customers return the same identifier for both user and principal for individual accounts. For Nominated Representatives, separating these identifiers is more logical.

Info

The userId and the principalId can be whatever you want, but we recommend not having PII in the string (i.e., don’t put an email address or phone number in there) because this data is stored within our consent store. A UUID is best, but anything will work.

Example In this example the user has both personal accounts and is a nominated representative of Biza Pty Ltd which also has accounts with the Data Holder.

  1. Consent is initiated with the Data Holder and the user inputs their username jdoe@biza.io
  2. The adapter is called with the username jdoe@biza.io dependent on the type of Authentication method in use with the customer's deployment:
    • Biza Managed: The adapter responses with a userId of jdoe (note the real system this should be a UUID that represents jdoe rather than a username) and the mobile number to SMS an OTP to. The HaaS environment then sends an OTP to the mobile number, the user enters the OTP into the HaaS consent flow and the HaaS environment checks it before calling Get User Principals for that userId
    • Double Blinded: You dispatch the OTP and we then call Login Verify.
  3. Because the user has both personal accounts and is a nominated representative for Biza Pty Ltd, the user actually has two principals returned. One to share John Doe and the other to share Biza Ptd Ltd.
  4. The HaaS environment then shows the profile selector step to the user to determine what principal ("Consumer") they wish to share data from. To get the name of the principal, the HaaS environment calls Get User for each principal supplied in the return response from (3):
    • One with user=jdoe and with principal John Doe.
    • One with user=jdoe and with principal Biza Pty Ltd.
Note

The principalName from the Get User response is used to display the name of the entity in the profile selector.

  1. Once the user has selected a principal, a call to List Banking Accounts or List Energy Accounts (dependent on sector) pertaining to the selected principal is made to provide the user a set of accounts to initiate sharing on.
  2. The consent process continues as per normal.
Note

The Get User call is a significant optimisation. If the HaaS environment must call Get Customer to retrieve the name of the principal instead which can result in significant load increases associated with addresses and phone numbers that are, in effect, discarded.

Examples​

Some examples of Get User with respect to POA and Nominated Representatives.

If a user had POA over the user+principal of cdoe+ Chris Doe:

  • getUser(userId=”jdoe”, principal=”John Doe”) could return: ATOs = ATOs = [( type=”POWER_OF_ATTORNEY”, user=”cdoe”, principal=”Chris Doe”)]

If a user (jdoe) holds Nominated Representative status over Biza Pty Ltd the response is actually a reflection of the userId specified:

  • getUser(userId=”jdoe”, principal=”Biza Pty Ltd”) could return: ATOs = [( type=”NOMINATED_REPRESENTATIVE”, user=”jdoe”, principal=”Biza Pty Ltd”)]
Note

Flexibility is built into the HaaS implementation to cater for the variety of systems we are currently exposed to through the data adapter.