Autenticação
Visão Geral
A API PIX Bacen utiliza o mesmo sistema de autenticação da API padrão Avista. Todas as requisições devem incluir um token Bearer válido no header Authorization.
A autenticação é idêntica a API padrão. Se você já possui credenciais, pode usá-las diretamente.
Obtendo o Token
Endpoint
POST /oauth/tokenRequest
curl -X POST https://api.public.firebanking.com.br/oauth/token \
-H "Content-Type: application/json" \
-d '{
"clientId": "seu-client-id",
"clientSecret": "seu-client-secret"
}'const response = await fetch('https://api.public.firebanking.com.br/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
clientId: 'seu-client-id',
clientSecret: 'seu-client-secret',
}),
});
const { access_token } = await response.json();import requests
response = requests.post(
'https://api.public.firebanking.com.br/oauth/token',
json={
'clientId': 'seu-client-id',
'clientSecret': 'seu-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"
}Usando o Token
Inclua o token em todas as requisições da API PIX Bacen:
curl -X PUT https://api.public.firebanking.com.br/cob/abc123 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'Parâmetros de Autenticação
Identificador único da sua aplicação. Fornecido durante o cadastro.
Chave secreta da sua aplicação. Deve ter entre 8 e 64 caracteres.
Nunca exponha o clientSecret em código frontend ou repositórios públicos.
Campos da Resposta
access_tokenstringToken JWT para autenticação nas requisições.
token_typestringTipo do token. Sempre "Bearer".
expires_innumberTempo de vida do token em segundos. Padrão: 3600 (1 hora).
scopestringEscopos de permissão do token.
Renovação do Token
O token expira após expires_in segundos. Implemente renovação automática:
class TokenManager {
private token: string | null = null;
private expiresAt: number = 0;
async getToken(): Promise<string> {
// Renovar 5 minutos antes de expirar
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.public.firebanking.com.br/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);
}
}Erros de Autenticação
| Código | Descrição | Solução |
|---|---|---|
| 401 | Token não fornecido | Inclua o header Authorization: Bearer <token> |
| 401 | Token inválido | Verifique se o token está correto e não expirou |
| 401 | Token expirado | Obtenha um novo token via /oauth/token |
| 403 | Permissão negada | Verifique os escopos do token |