Autenticação

Token flow OAuth-style com chaves de API, refresh e revogação.

Fluxo de autenticação

Merchant BRPix API | | |-- POST /v1/auth/token (key_id+secret) -->| | |-- verifica bcrypt hash | |-- valida IP whitelist |<-- 200 access_token (15 min) ----------| | + refresh_token (7 dias) | | | |-- GET /v1/balance | | Authorization: Bearer access_token -->| |<-- 200 saldo -------------------------------| | | |-- POST /v1/auth/refresh (refresh_token) -->| |<-- 200 novo access_token (15 min) ---------|

POST /v1/auth/token

Troca credenciais (key_id + key_secret) por um par de tokens.

# Requisição
curl -s -X POST https://api.brpix.app/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "bk_live_abc123",
    "key_secret": "sk_live_xxxxxxxxxxxxx"
  }'

# Resposta 200
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900,
  "refresh_token": "d2f4a8b1-1234-5678-abcd-ef0123456789"
}

POST /v1/auth/refresh

Renova o access_token usando o refresh_token sem precisar das credenciais originais.

# Requisição
curl -s -X POST https://api.brpix.app/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "d2f4a8b1-1234-5678-abcd-ef0123456789"}'

# Resposta 200
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

DELETE /v1/auth/revoke

Invalida um refresh_token antes de seu vencimento (7 dias). Use ao deslogar ou rotacionar credenciais.

# Requisição (exige Bearer token válido)
curl -s -X DELETE https://api.brpix.app/v1/auth/revoke \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "d2f4a8b1-1234-5678-abcd-ef0123456789"}'

# Resposta 204 No Content

Scopes disponíveis

Scope	Descrição
balance:read	Consultar saldo disponível, a receber e bloqueado
statement:read	Consultar extrato (ledger entries paginado)
pix_in:create	Gerar cobranças Pix In e cancelar cobranças pendentes
pix_in:read	Consultar cobranças Pix In e chaves Pix cadastradas
pix_out:create	Iniciar transferências Pix Out ⚠ Requer IPs autorizados
pix_out:read	Consultar status de transferências Pix Out

Scopes são cumulativos. Uma chave pode ter vários scopes. Definidos no painel BRPix em Configurações → API Keys ao criar ou editar uma chave.

IP Whitelist

Se a chave de API tiver IPs autorizados configurados, requisições de IPs não autorizados recebem 403 com código IP_NOT_AUTHORIZED. Para chaves sem IP whitelist, qualquer IP é aceito.

Recomendação para pix_out:create: configure sempre uma lista de IPs autorizados para chaves com scope de cashout, para mitigar uso indevido em caso de vazamento do key_secret.

mTLS

Autenticação mútua TLS (mTLS) está planejada para versões futuras. Quando disponível, o certificado do cliente será validado junto ao Bearer token.