Onboarding

Onboarding your Users with Connect allows:

• Users to create their account themselves using a public endpoint
• You to use our OAuth provider to authenticate your Users, provides permissions management and a lost password feature
• You to see all Users in pending KYC pre-review status in the Dashboard

When onboarding with Connect, your Users have two distinct IDs:

• trzConnectUserId used during the Connect Onboarding and when changing password
• userId used across the whole API to identify the User

Configuration

Onboarding Users with Connect requires the following initial configuration.

Parameters

Attribute	Description
onboardingSuccessCallBack	The URL the User is redirected to, upon successful activation of their account
onboardingErrorCallBack	The URL the User is redirected to, upon failure of the activation of their account

CURL

curl -X PUT {baseUrl}/core-connect/onboarding/config \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{
		"onboardingSuccessCallBack": "{sucessUrl}",
		"onboardingErrorCallBack": "{errorUrl}"
	}'

Creation

To create the User via Connect, you can use the following public endpoint.

Parameters

Attribute	Description
email	The email address of the User. It must be a unique and valid email address.
password	The password chosen by the User. It is expected in cleartext and must currently pass the /^\S*(?=\S{8,})(?=\S*[\d])\S*$/ regular expression.

Any parameter accepted by the POST /v1/users endpoint can also be provided to this endpoint but are all optional.

CURL

curl -X POST {baseUrl}/core-connect/onboard/users \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{
		"email":"{userEmail}",
		"password": "{userPassword}"
	}'

Returns a 201 HTTP Status Code without any content and sends a confirmation email to the User's email address, to validate their account.

Tip – Emails are customizable

The associated Templates are email.user.onboarding_confirmation_html and email.user.onboarding_confirmation_text

When the User clicks on the link contained in the email:

• A user.create webhook is sent
• The User becomes usable across the API
• The User is redirected to the configured callback URL with query parameters containing the autorization_code and the trzConnectUserId such as {onboardingSuccessCallBack}?authorization_code={autorization_code}&trzConnectUserId={trzConnectUserId}

Retrieving the User ID

To retrieve the User's ID (userId), you can use the following request which authenticates the User without them having to enter their email or password again.

Parameters

Attribute	Description
grant_type	Set to authorization_code in this context.
client_id	Your client ID
code	The authorization_code provided in the previous step (it can be extracted from the query parameters using JavaScript).

CURL

curl -X POST {baseUrl}/oauth/token \
	--form 'grant_type="authorization_code"' \
	--form 'client_id="{yourClientId}"' \
	--form 'code="{authorization_code}"'

Returns a JSON Web Token (JWT) that contains the User's ID along with other information.

JSON

eyJ0eXAiOiJK[...]TSEFfMjU2In0.eyJpc3Mi[...]jYXRpb24ifQ.Z9RwLjz8XTb[...]4Eu_pn2rl1UCJCTfw

Your application can extract the userId by decoding the JWT using an appropriate decoding library.

JSON

{
	"iss": "treezor_connect",
	"iat": 1624439479,
	"exp": 1624443079,
	"sub": "79037e6e-c1e1-42f2-be9a-e249c767c476", // here is the trzConnectUserId
	"scope": [
		"keys",
		"legal",
		"read_only",
		"read_write",
		"read_all"
	],
	"userId": {userId},	// here is the userId
	"cards": [],
	"wallets": [],
	"children": [],
	"userType": "application"
}

This JWT also allows the User to be authenticated against our OAuth provider and the Treezor API for subsequent requests.

List complete vs. unfinished onboardings

You can list Users that are completely onboarded via Connect and users that have not finished the onboarding (not validated their email) using the following requests.

Completely onboarded

CURL

curl {baseUrl}/core-connect/users?onboardingComplete=1 \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Returns the list of TrzConnectUsers.

JSON

{
	"data":[
		{
			"username":"redacted1@treezor.com",
			"userId":1853336, // notice presence of a value
			"trzConnectUserId":"023f6bcc-d615-4e82-a5bf-aba34c86a108",
			// [...] some attributes have been hidden for clarity
		},
		{
			"username":"redacted2@treezor.com",
			"userId":1949557,  // notice presence of a value
			"trzConnectUserId":"04fcf0a1-0313-44b3-9f43-87552e396a7f",
			// [...] some attributes have been hidden for clarity
		}
	],
	"cursor":{
		"prev":null,
		"current":null,
		"next":"ey[...]0="
	}
}

Unfinished onboarding

CURL

curl {baseUrl}/core-connect/users?onboardingComplete=0 \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Returns the list of TrzConnectUsers.

JSON

{
	"data":[
		{
			"username":"redacted3@treezor.com",
			"userId":null, // notice the null value
			"trzConnectUserId":"064fdc8e-e022-4782-9d9c-abb7ed3af5c4",
			// [...] some attributes have been hidden for clarity
		},
		{
			"username":"redacted4@treezor.com",
			"userId":null, // notice the null value
			"trzConnectUserId":"06590239-1f13-4cc9-9f12-a55389570c78",
			// [...] some attributes have been hidden for clarity
		}
	],
	"cursor":{
		"prev":"ey[...]V9",
		"current":"ey[...]0=",
		"next":"ey[...]0="
	}
}

You can also distinguish a completely onboarded Users by the presence of a populated userId attribute. Users that have not finished the onboarding will have a null userId attribute.

Passwords

Two methods are available to change a password, one is while logged-in, the other is logged-out.

Configuration

Changing passwords using Connect requires an initial configuration step.

Using the following request, you can configure the password policy and a URL where the user is redirected after clicking on the password change link contained in an email.

Parameters

Attribute	Description
passwordChangeRedirectUrl	Defines the URL where the User is redirected when clicking on the link.
passwordPattern.minLength	Requires a minimum length to the password (the lowest accepted value is 12).
passwordPattern.requireLetters	Requires the presence of letters.
passwordPattern.requireCaseDiff	Requires the presence of both uppercase and lowercase letters.
passwordPattern.requireNumbers	Requires the presence of numbers.
passwordPattern.requireSpecialCharacter	Requires the presence of specials characters.

CURL

curl -X PUT {baseUrl}/core-connect/password/config \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{
		"passwordChangeRedirectUrl": "string|url",
		"passwordPattern": {
			"minLength": int,
			"requireLetters": bool,
			"requireCaseDiff": bool,
			"requireNumbers": bool,
			"requireSpecialCharacter": bool
		}
	}'

While logged-in

If the User is logged-in and has the read_write scope, they can change their password using the following request

Parameters

• trzConnectUserId is their trzConnectUserId as seen in previous steps
• password is their new password, complying to the previously defined password policy.

CURL

curl -X PUT {baseUrl}/core-connect/users/{trzConnectUserId}/password \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{
		"password": "string"
	}'

While logged-out

If the User has lost their password, changing it happens in the following sequence:

• The User first requests a password change using the POST /core-connect/password/forgot public endpoint and their email address
• The User receives an email containing a link
• The User clicks the link which takes them to passwordChangeRedirectUrl (a form on your application or website)
• The User enters a new password in your form and posts it to the PUT /core-connect/password/change public endpoint, along with the token provided in the URL query parameters

To request a password change, the User can use the following request.

Parameters

• email mandatory, is the User's email

CURL

curl -X POST {baseUrl}/core-connect/password/forgot \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{
		"email": "string"
	}'

Returns a 204 HTTP Status Code in all cases, even if the email address doesn't exist.

If the email address exists, and email is sent to it.

The User clicks the link and is redirected to the passwordChangeRedirectUrl URL (a password change form hosted on your application or website). A unique token is added to the URL as a query parameter, allowing you to pass it to the next endpoint.

The User enters a new password and posts the form to the following public endpoint

Parameters

• token is a unique token provided to you in a query parameter
• email is the current email of the user
• password is the new password of the user, complying to the previously defined password policy

bash

curl -X PUT {baseUrl}/core-connect/password/change \
	-d '{
		"token": "string",
		"email": "string",
		"password": "string"
	}'

The token is valid for 24 hours and can only be used once.

If the change is successful

A 204 HTTP Status Code is returned, without content.

If the change fails

A 400 HTTP Status Code is returned with one of the following errors :

• Expired token
• Invalid token
• Token has already been used

Endpoints

You should add a confirmationCode parameter in the query to improve on security.

Endpoint	Description
/onboard/users	Start the onboarding, create a user with a UUID.
/onboard/users/confirm/{trzConnectUserId}/{confirmationCode}	Link to confirm the email address
/onboard/users/{trzConnectUserId}/{confirmationCode}	Fetch a user's data during onboarding
/onboarding/users/{trzConnectUserId}/{confirmationCode}	Finalize the onboarding, fetch a user's JWT