The authentication method described in this doc refers to the method to use Toqio's public API. If you are integrating a new financial provider into Toqio please refer to the Integration Hub API.
The authentication method to connect to our public API will be OAuth 2.0 Client Credentials Grant Type
Retrieving token
curl -X POST 'https://api.toq.io/iam/oauth/token' \
--header 'Authorization: Basic <encoded base64 username:password>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \You will receive a response as follows
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJz...",
"expires_in": 3599,
"jti": "f8e4b107-26e5-494f-a59e-d008a4fdfcc4",
"scope": "",
"token_type": "bearer"
}All API request must be called using the access_token received using the "Authorization" header inside each request:
Authorization: "Bearer {access_token}"Token lifetime and caching
The token response includes an expires_in field giving the token's remaining lifetime in seconds:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3599,
"scope": "openid",
"jti": "3c9f1a72-5e04-4c8b-9f21-7ab5d0e6c418"
}Always read expires_in from the response rather than hardcoding a lifetime. Token lifetime is configured per customer and may differ between your environments, so a value that is correct for one integration will not necessarily be correct for another.
Cache the token and reuse it until shortly before it expires. A safety margin of 30–60 seconds before expiry is a common choice, and lets you refresh without ever presenting an expired token.
Do not request a new token for each API call. The token endpoint is not designed for per-request use: minting a token per call adds a round trip to every operation, consumes capacity on both sides, and increases connection churn against the platform (see Connection handling and timeouts).
If you receive 401 Unauthorized on a request you expected to succeed, request a new token and retry once. A token cache should treat that as a signal to refresh rather than as a failure to surface to the caller.