OAuth

Configure the OAuth flow

The user authenticates at Wealth Reader, returns to your redirect_uri with a code, and you exchange it for the same JSON as the iframe callback.

Use this path if you cannot embed the iframe (native app or a redirect flow). If your web app can host an iframe, use iframe frontend instead.

Quick path

Authorise the domain with access_type=oauth.
Generate nonce, state and code_verifier. Compute challenge_code. Encode wr_conf as hexadecimal. Store nonce and code_verifier.
Redirect the user to https://oauth.wealthreader.com/oauth2/ with those parameters.
Receive a GET on your redirect_uri with nonce and code.
POST to https://oauth.wealthreader.com/token/ and obtain the bank payload.

1. Authorise the domain

domain must be the same URL you will use as redirect_uri and as url_callback.

curl --location 'https://api.wealthreader.com/domains/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'method=add' \
  --data-urlencode 'api_key=YOUR_API_KEY' \
  --data-urlencode 'domain=https://example.com/oauth/success.php' \
  --data-urlencode 'url_callback=https://example.com/oauth/success.php' \
  --data-urlencode 'access_type=oauth' \
  --data-urlencode 'tokenize=1'

You can also register the domain from the client area by choosing OAuth integration.

2. Generate the challenge values

Generate three random 41-character alphanumeric strings (A-Za-z0-9) and convert them to hexadecimal (bin2hex). Each hexadecimal value is 82 characters long.

Value	How to obtain it	Sent in
`redirect_uri`	Your return URL, the same one you authorised	query and `POST /token/`
`nonce`	41 chars → hex	query; returned on the `GET`
`state`	41 chars → hex	query
`code_verifier`	41 chars → hex	`POST /token/` only (not in the query)
`challenge_code`	SHA-256 of `code_verifier` (hex digest)	query, as `challenge_code`
`wr_conf`	Selector configuration JSON → hex	query

wr_conf accepts the same fields as iframe frontend. Example before converting to hexadecimal:

{
  "operation_id": "op_a1b2c3d4e5f6",
  "entities_to_display": [],
  "wait_full_response": true
}

Hexadecimal of that JSON:

7b226f7065726174696f6e5f6964223a226f705f613162326333643465356636222c22656e7469746965735f746f5f646973706c6179223a5b5d2c22776169745f66756c6c5f726573706f6e7365223a747275657d

Converting wr_conf to hexadecimal does not generate nonce, state or code_verifier. Those three values are created separately and you must persist them (keyed by nonce) until the POST /token/.

PHP example, equivalent to what we use internally:

function randomAlnum($length)
{
    $alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    $value = '';
    for ($i = 0; $i < $length; $i++) {
        $value .= $alphabet[random_int(0, strlen($alphabet) - 1)];
    }
    return $value;
}

$nonce = bin2hex(randomAlnum(41));
$state = bin2hex(randomAlnum(41));
$code_verifier = bin2hex(randomAlnum(41));
$challenge_code = hash('sha256', $code_verifier);

$wr_conf = bin2hex(json_encode([
    'operation_id' => 'op_a1b2c3d4e5f6',
    'entities_to_display' => [],
    'wait_full_response' => true,
]));

3. Redirect the user

Build the query and redirect. Example with values that match each other:

https://oauth.wealthreader.com/oauth2/?challenge_code=c725133644f703a5f069a09583fa981eb5b8820071a4450f8d47ff8b1c6a879a
&code_challenge_method=S256
&redirect_uri=https://example.com/oauth/success.php
&response_type=code
&state=73684148464b3778795873626d724e62734749724336685a7a687854336c317934524f516831316a45
&nonce=696d6a716d4a47746d714e52656562496f61786468765a30335a4b4a646d6c546c5339654e42586573
&wr_conf=7b226f7065726174696f6e5f6964223a226f705f613162326333643465356636222c22656e7469746965735f746f5f646973706c6179223a5b5d2c22776169745f66756c6c5f726573706f6e7365223a747275657d

The user sees the bank selector, authenticates, and when they finish Wealth Reader sends them back to your redirect_uri.

4. Receive the GET on `redirect_uri`

https://example.com/oauth/success.php?nonce=696d6a716d4a47746d714e52656562496f61786468765a30335a4b4a646d6c546c5339654e42586573
&code=1234567890abcdef1234567890abcdef1234567890a

Use the nonce to recover the code_verifier you stored in step 2. If the nonce is not one you issued, discard the request.

5. Complete the challenge

curl --location --request POST 'https://oauth.wealthreader.com/token/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri=https://example.com/oauth/success.php' \
  --data-urlencode 'code=1234567890abcdef1234567890abcdef1234567890a' \
  --data-urlencode 'code_verifier=6634413364504337675230375a624671644f644d42414241303037737374684f494877477649723433'

Field	Value
`grant_type`	`authorization_code`
`redirect_uri`	Exactly the same as in step 3
`code`	The one from the `GET`
`code_verifier`	The hexadecimal value you generated in step 2

If the values match, the response is the bank JSON (same schema as the iframe callback): success, payload and statistics (operation_id, token, code).

Store token and code if you will later refresh with POST https://api.wealthreader.com/entities/.

Sample code

There is a Java example (JBang / Java 17) that generates the parameters and completes the challenge:

Download Java example (ZIP)

If you need the same flow in another language, write to support@wealthreader.com.

Last updated 2026-08-15