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:
- Obtaining your token – Call the
/oauth/token
endpoint to get a JWT. - 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.
bash
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;
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.
bash
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:
bash
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.