Request a Customers access token

A Customers access token authenticates your calls to Fintecture's customer endpoints. Like PIS, it uses the OAuth 2.0 client credentials flow: exchange your application credentials for a short-lived Bearer token — no user interaction involved.

How it works

1. Create a Fintecture account
2. Register a client application and get the credentials (i.e. the app_id and app_secret) associated to it
3. Encode your credentials using Base64 (base64({app_id}:{app_secret})) to build the Authorization: Basic header
4. Request an access token with the customers scope
5. Use the returned access_token as a Bearer token on every customer endpoint
6. Track expires_in and request a new token before it expires

❗️

Keep your app_secret secret

Request tokens from your backend only. Never embed the app_secret (or a valid access token) in a browser, mobile app, or public repository.

1. Build the Authorization header

Concatenate your credentials with a colon and Base64-encode the result:

echo -n "your_app_id:your_app_secret" | base64

The header then looks like:

Authorization: Basic eW91cl9hcHBfaWQ6eW91cl9hcHBfc2VjcmV0

2. Request the token

Call POST /oauth/accesstoken with a form-encoded body (grant_type, app_id, scope):

curl -X POST "https://api.sandbox.fintecture.com/oauth/accesstoken" \
  -H "Authorization: Basic $(echo -n "$APP_ID:$APP_SECRET" | base64 | tr -d '\n')" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "app_id=$APP_ID" \
  -d "scope=customers"

const APP_ID = process.env.FINTECTURE_APP_ID;
const APP_SECRET = process.env.FINTECTURE_APP_SECRET;

const basic = Buffer.from(`${APP_ID}:${APP_SECRET}`).toString('base64');

const response = await fetch('https://api.sandbox.fintecture.com/oauth/accesstoken', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${basic}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    app_id: APP_ID,
    scope: 'customers',
  }),
});

const { access_token, expires_in } = await response.json();

import base64
import os

import requests

app_id = os.environ["FINTECTURE_APP_ID"]
app_secret = os.environ["FINTECTURE_APP_SECRET"]

basic = base64.b64encode(f"{app_id}:{app_secret}".encode()).decode()

response = requests.post(
    "https://api.sandbox.fintecture.com/oauth/accesstoken",
    headers={"Authorization": f"Basic {basic}"},
    data={"grant_type": "client_credentials", "app_id": app_id, "scope": "customers"},
)
response.raise_for_status()
token = response.json()["access_token"]

📘

Sandbox vs production

The examples above target the sandbox. For production, use https://api.fintecture.com — and remember that each environment has its own app_id / app_secret: sandbox credentials return 401 in production, and vice versa.

3. Read the response

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJub25lIn0.eyJleHAiOjE1MTQwODA0MjQsI",
  "expires_in": 599
}

4. Use the token

Send the token in the Authorization header of every customer endpoint:

Authorization: Bearer eyJhbGciOiJub25lIn0.eyJleHAiOjE1MTQwODA0MjQsI

📘

In production, requests also require a signature on top of the Bearer token. See HTTP Signature.

Token lifetime & renewal

Customers tokens are short-lived and have no refresh token — renewing simply means requesting a new token with the same call as above. In practice:

• Cache the token and reuse it for all calls until it expires — don't request a new token per API call.
• Track expiry from expires_in and renew slightly before (e.g. 60 seconds of safety margin).
• On a 401 response, request a fresh token and retry once.

Troubleshooting

Every error response contains a log_id — include it when you contact support so we can trace the exact call.