Autenticação

Visão Geral

A API PIX Bacen utiliza o mesmo sistema de autenticação da API padrão Fire Banking. Todas as requisições devem incluir um token Bearer válido no header Authorization.

A autenticação é idêntica à API padrão. Se você já possui credenciais, pode usá-las diretamente.

Obtendo o Token

Endpoint

POST /oauth/token

Request

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

string

obrigatório

Identificador único da sua aplicação. Fornecido durante o cadastro.

string

obrigatório

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

string

Token JWT para autenticação nas requisições.

string

Tipo do token. Sempre "Bearer".

number

Tempo de vida do token em segundos. Padrão: 3600 (1 hora).

string

Escopos 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

Boas Práticas

Armazene credenciais com segurança

Use variáveis de ambiente
Nunca commite credenciais no código
Use secret managers em produção (AWS Secrets Manager, HashiCorp Vault)

Implemente cache de token

Cache o token até próximo da expiração
Renove alguns minutos antes de expirar
Evite requisições desnecessárias ao endpoint de token

Use HTTPS sempre

Todas as requisições devem usar HTTPS
Verifique certificados SSL/TLS
Configure timeouts apropriados

Próximos Passos

Ativação

Ative o modo PIX Bacen na sua conta

Criar Cobrança

Faça sua primeira cobrança

Introdução

Endpoints

Webhooks V2

Visão Geral

Obtendo o Token

Endpoint

Request

Response

Usando o Token

Parâmetros de Autenticação

Campos da Resposta

Renovação do Token

Erros de Autenticação

Boas Práticas

Próximos Passos

Ativação

Criar Cobrança

​Visão Geral

​Obtendo o Token

​Endpoint

​Request

​Response

​Usando o Token

​Parâmetros de Autenticação

​Campos da Resposta

​Renovação do Token

​Erros de Autenticação

​Boas Práticas

​Próximos Passos

Ativação

Criar Cobrança

Visão Geral

Obtendo o Token

Endpoint

Request

Response

Usando o Token

Parâmetros de Autenticação

Campos da Resposta

Renovação do Token

Erros de Autenticação

Boas Práticas

Próximos Passos