Authentication
Overview
The PIX Bacen API uses the same authentication system as the standard EYT 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 /api/auth/tokenThe X.509 certificate must be sent URL-encoded in the X-SSL-Client-Cert header. The system validates the certificate's SHA256 fingerprint against the records linked to the account.
Request
curl -X POST https://api.gateway.eyt.com.br/api/auth/token \
-H "Content-Type: application/json" \
-H "X-SSL-Client-Cert: -----BEGIN%20CERTIFICATE-----%0AMIIB..." \
-d '{
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}'const fs = require('fs');
const certificate = fs.readFileSync('./client-cert.pem', 'utf8');
const encodedCert = encodeURIComponent(certificate);
const response = await fetch('https://api.gateway.eyt.com.br/api/auth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-SSL-Client-Cert': encodedCert,
},
body: JSON.stringify({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
}),
});
const { access_token } = await response.json();import requests
import urllib.parse
with open('client-cert.pem', 'r') as f:
certificate = f.read()
encoded_cert = urllib.parse.quote(certificate)
response = requests.post(
'https://api.gateway.eyt.com.br/api/auth/token',
headers={'X-SSL-Client-Cert': encoded_cert},
json={
'clientId': 'your-client-id',
'clientSecret': 'your-client-secret'
}
)
access_token = response.json()['access_token']Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 1800
}Using the Token
Include the token in all PIX Bacen API requests:
curl -X PUT https://api.gateway.eyt.com.br/cob/abc123 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'Authentication Parameters
Client X.509 certificate, in PEM format and URL-encoded, linked to your account.
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. Always 1800 (30 minutes).
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 fs = require('fs');
const certificate = fs.readFileSync(process.env.CLIENT_CERT_PATH, 'utf8');
const encodedCert = encodeURIComponent(certificate);
const response = await fetch('https://api.gateway.eyt.com.br/api/auth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-SSL-Client-Cert': encodedCert,
},
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 /api/auth/token |
| 400/401/403 | Certificate or credential error on /api/auth/token | See the certificate errors in the standard authentication guide |