Chaves de API
Como criar e gerenciar chaves de API para autenticação
Visão Geral
Chaves de API são o mecanismo de autenticação para integrar com a API SoarLabz. Cada chave é composta por um par:
- Public Key (
pk_live_...): identifica a chave nas requisições - Secret Key (
sk_live_...): segredo usado na autenticação
A Secret Key é exibida apenas uma vez no momento da criação. Se perdê-la, será necessário revogar a chave e criar uma nova.
Criando uma Chave
curl -X POST https://api.payhubrasil.com.br/v1/api-keys \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"name": "Integração Produção",
"ip_whitelist": ["203.0.113.10"]
}'const response = await fetch('https://api.payhubrasil.com.br/v1/api-keys', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify
Resposta
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Integração Produção",
"public_key": "pk_live_abc123def456",
"secret_key": "sk_live_xyz789ghi012",
"is_active": true,
"created_at": "2026-02-11T10:00:00Z"
}
}| Campo | Obrigatório | Descrição |
|---|---|---|
name | Sim | Nome identificador da chave (1-50 caracteres) |
ip_whitelist | Não | Lista de IPs autorizados (IPv4) |
Listando Chaves
curl -X GET https://api.payhubrasil.com.br/v1/api-keys \
-H "Authorization: Basic {credentials}"A Secret Key nunca é retornada em listagens. Apenas a Public Key é visível após a criação.
Atualizando uma Chave
Você pode alterar o nome, ativar/desativar a chave ou modificar a whitelist de IPs:
curl -X PATCH https://api.payhubrasil.com.br/v1/api-keys/{id} \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"name": "Novo Nome",
"is_active": false,
"ip_whitelist": ["203.0.113.10", "203.0.113.20"]
}'Removendo a restrição de IP
Para remover a whitelist e permitir requisições de qualquer IP:
{
"ip_whitelist": null
}Revogando uma Chave
A revogação remove permanentemente a chave:
curl -X DELETE https://api.payhubrasil.com.br/v1/api-keys/{id} \
-H "Authorization: Basic {credentials}"A revogação é irreversível. Todas as integrações que utilizam essa chave deixarão de funcionar imediatamente.
Boas Práticas
Uma chave por ambiente
Crie chaves separadas para desenvolvimento, staging e produção.
Restrinja por IP
Use a whitelist para limitar o acesso apenas aos IPs dos seus servidores.
Rotacione periodicamente
Crie uma nova chave, migre a integração e revogue a antiga.
Monitore o uso
Acompanhe o campo last_used_at para identificar chaves sem uso.