Authentication

Treezor leverages the OAuth2 framework and JSON Web Token (JWT) which allows for a wide range of authentication flows. Treezor also relies on Mutual TLS authentication as an additional security layer.

Authenticating is a two-step process:

1. Obtaining your token – Call the /oauth/token endpoint to get a JWT.
2. Using the token – For each subsequent request, include this JWT in an Authorization header.

Obtaining an access token (JWT)

As part of your onboarding process, your Treezor Account Manager has provided you with your credentials including client_id and client_secret.

Security – Keep your credentials safe

Authentication uses client_id and client_secret. These are extremely sensitive credentials and must be kept safe and secret. See the Credentials article for more information.

Use the following request to authenticate and get your JWT, using the relevant {baseUrl} depending on the environment.

CURL

curl -X POST {baseUrl}/oauth/token \
	--form 'grant_type="client_credentials"' \		# required
	--form 'client_id="{yourClientId}"' \			# required
	--form 'client_secret="{yourClientSecret}"'		# required
#	--form 'scope="{scope}"'						# optional, to specify scope

PHP

// composer require php-curl-class/php-curl-class
echo (new Curl\Curl)
	->post('{baseUrl}/oauth/token', [
		'grant_type'	=>'client_credentials',	// required
		'client_id'		=>'{yourClientId}',		// required
		'client_secret'	=>'{yourClientSecret}',	// required
//		'scope'			=>'{scope}',		// optional, to specify scope
	])
	->access_token;

Node.JS

const axios = require('axios');

async function authenticate() {
  try {
    const baseUrl = '{baseUrl}/'; // replace with your Treezor API base URL
    const yourClientId = 'your_client_id'; // replace with your client id
    const yourClientSecret = 'your_client_secret'; // replace with your client secret

    const response = await axios.post(`${baseUrl}oauth/token`, {
      grant_type: 'client_credentials',
      client_id: yourClientId,
      client_secret: yourClientSecret,
    });

    console.log('Authentication successful!');
    console.log('Access token:', response.data.access_token);
  } catch (error) {
    if (!error.response) {
      console.log('Error during network request');
    } else {
      console.log(`Authentification failed with error code ${error.response.status}`);
    }
  }
}

authenticate();

The following JSON object is returned if successful, the access_token field being your JWT:

JSON

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "{accessToken}"
	// optionally, the response may contain a "refresh_token" property and token.
}

You're now authenticated to the Treezor API. Keep your access_token at hand, since it will be used during the next steps.

Note – The access token expires after 1 hour, so you need to:

• Cache the token (avoiding unnecessary hits to the authentication endpoint)
• Renew or refresh the token before it expires (not applicable to all situations)

Using the token

You can now use your JWT in the Authorization header to make your API calls as follows:

• Bearer – The type of your token. Make sure to keep the capitalization and space.
• {accessToken} – The JSON Web Token, referred to as the accessToken in the documentation examples.

The following example illustrates how a typical request to the API is structured.

CURL

curl -X GET {baseUrl}/example/of/endpoint \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json'

PHP

// composer require php-curl-class/php-curl-class
use Curl\Curl;

$curl = (new Curl)
	->setHeader('Authorization', 'Bearer {accessToken}');
echo $curl->get('{baseUrl}/example/of/endpoint');

Refreshing the token

A token can be refreshed up to a month after the initial authentication. After a month, you will have to start the authentication process again.

Availability – Refresh is only possible with password grant and authorization code flows

If the grant_type is client_credentials, you cannot refresh a token.

Request

The following example asks for a refreshed token:

CURL

curl -X POST {baseUrl}/oauth/token \ 
	--form 'grant_type="refresh_token"' \ 		# required
	--form 'client_id="{yourClientId}"' \ 		# required
	--form 'scope="user admin"' \  				    # optional, this shows multiple scopes
	--form 'refresh_token="{yourRefreshToken}"'	# required, your previously issued refreshToken

Response

JSON

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "{accessToken}",
    "refresh_token": "{accessTokenAllowingForJwtRefresh}"
}

You are now able to use the newly provided token.

Tip – Open-source libraries may help abstract token management

Treezor doesn't provide client libraries or SDKs to consume Treezor API, but some open-source tools are available to help you.

Scopes & Permissions

A Scope is similar to a permission; depending on the scope, you may or may not be able to view and alter certain data. Each user can have one or multiple scopes.

All endpoints are scope-restricted, you need to use an appropriate scope to access an endpoint.

Available scopes

Scope	Granted access
read_only	All GET endpoints (except legal and admin) End user oriented
read_write	All PUT, POST, and DELETE endpoints (except legal and admin) End user oriented
admin	API Configuration endpoints Use carefully
legal	KYC, users and end user documents endpoints
support_user_management	Support users endpoints

Best practice – Align your Scopes with the default Roles

The Dashboard comes with a set of Roles, which are a concatenation of the existing Scopes. Treezor advises you create Roles in the same way for specific developments.

Scope selection

The scope selection happens when you authenticate, scopes get embedded in the JWT used for subsequent requests to the API.

During authentication, you have the choice to either:

• A) Specify the desired scopes
• B) Don't specify anything

A) Specify the desired scopes

In this case, you are provided with the intersection of the desired scopes and the user's available scopes.

The requested scopes are expected in the scope request parameter. If more than one scope is requested, they should be space separated (e.g., admin read_write).

Consider the following desired scopes and user scopes.

user_scopes = ['A', 'B', 'C'];
desired_scopes = ['A', 'B', 'D'];

The returned token will cover scopes that are present in both: user scopes and desired scopes

returned_scopes = ['A', 'B'];

Example

curl -X POST {baseUrl}/oauth/token \
  --form 'grant_type="client_credentials"' \		# mandatory
  --form 'client_id="{yourClientId}"' \			# mandatory
  --form 'client_secret="{yourClientSecret}"' \	# mandatory
  --form 'scope="admin"'							# optional, if you want a specific scope

B) Don't specify anything

In this case, you are provided with all of the user's scopes.

Consider the following user scopes and no desired scopes.

user_scopes = ['A', 'B', 'C'];

The returned token will cover all of the user's scopes (so be careful!)

returned_scopes = ['A', 'B', 'C'];

Scopes behavior

When using end user-oriented scopes (read_only or read_write without other scopes), the API only returns information related to the authenticated user.

For the following requests made with the read_only scope, the API returns:

• GET /wallets – The wallets of the authenticated User (and their children's).
• GET /documents – The documents of the authenticated User (and their children's).