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 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 (ex. "admin" or "admin read_all")

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 (ex. 'admin' or 'admin read_all')
	])
	->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.