Authentication
Overview
The PIX Bacen API uses the same authentication system as the standard Avista API. All requests must include a valid Bearer token in the Authorization header.
Authentication is identical to the standard API. If you already have credentials, you can use them directly.
Obtaining a Token
Endpoint
POST /oauth/tokenRequest
curl -X POST https://api.ntxpay.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}'const response = await fetch('https://api.ntxpay.com/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
}),
});
const { access_token } = await response.json();import requests
response = requests.post(
'https://api.ntxpay.com/oauth/token',
json={
'clientId': 'your-client-id',
'clientSecret': 'your-client-secret'
}
)
access_token = response.json()['access_token']Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "pix:read pix:write balance:read"
}Using the Token
Include the token in all PIX Bacen API requests:
curl -X PUT https://api.ntxpay.com/cob/abc123 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'Authentication Parameters
Unique identifier for your application. Provided during registration.
Secret key for your application. Must be between 8 and 64 characters.
Never expose the clientSecret in frontend code or public repositories.
Response Fields
access_tokenstringJWT token for authenticating requests.
token_typestringToken type. Always "Bearer".
expires_innumberToken lifetime in seconds. Default: 3600 (1 hour).
scopestringToken permission scopes.
Token Renewal
The token expires after expires_in seconds. Implement automatic renewal:
class TokenManager {
private token: string | null = null;
private expiresAt: number = 0;
async getToken(): Promise<string> {
// Renew 5 minutes before expiration
if (!this.token || Date.now() >= this.expiresAt - 300000) {
await this.refreshToken();
}
return this.token!;
}
private async refreshToken(): Promise<void> {
const response = await fetch('https://api.ntxpay.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientId: process.env.CLIENT_ID,
clientSecret: process.env.CLIENT_SECRET,
}),
});
const data = await response.json();
this.token = data.access_token;
this.expiresAt = Date.now() + (data.expires_in * 1000);
}
}Authentication Errors
| Code | Description | Solution |
|---|---|---|
| 401 | Token not provided | Include the Authorization: Bearer <token> header |
| 401 | Invalid token | Verify that the token is correct and has not expired |
| 401 | Expired token | Obtain a new token via /oauth/token |
| 403 | Permission denied | Check the token scopes |