Endpoint de Autenticação (Geração de Token)
Ainda não é cliente?
Para obter credenciais e começar a integrar, entre em contato com nosso time comercial pelo e-mail comercial@bigools.com.br. Vamos provisionar sua conta (tenant), ambientes e chaves de acesso.
Por que este endpoint existe
Todas as APIs da Bigools são protegidas. Em vez de enviar usuário/senha a cada requisição (o que seria inseguro e pouco eficiente), você primeiro autentica sua aplicação neste endpoint e recebe um token de acesso do tipo Bearer.
Esse token é apresentado nas chamadas seguintes e permite que nossa plataforma:
Identifique com precisão quem está fazendo a requisição (cliente, aplicação e ambiente).
Aplique segurança (validação de assinatura, expiração, revogação, rate limiting e proteção contra abuso).
Controle de permissões (escopos) por serviço/ação, garantindo o mínimo necessário de acesso.
Audite e rastreie todas as operações por cliente e por ambiente.
Simplifique o uso das demais APIs: você só envia o header Authorization: Bearer .
Em termos práticos, o token funciona como um comprovante assinado de identidade e autorização, contendo informações como o seu tenant, escopos/permissões concedidos e janelas de validade (emissão/expiração).
Como funciona (visão geral)
Sua aplicação envia suas credenciais para o endpoint de autenticação (POST /auth/token).
O fluxo pode variar conforme o caso de uso (por exemplo, client credentials para servidores e integrações backend).
A Bigools retorna um access_token e o tempo de expiração (expires_in).
Nas chamadas às demais APIs, inclua o header:
Authorization: Bearer <access_token>
Quando expirar, renove o token repetindo o passo 1.
Importante: Tokens são específicos por ambiente (ex.: dev, hml, sandbox, prod). Use as credenciais e o endpoint correspondentes ao ambiente em que você está integrando.
Boas práticas de segurança
Transmita sempre por HTTPS.
Não registre o token completo em logs de aplicação; se precisar, mascare.
Armazene segredos com segurança (ex.: vaults).
Rotacione credenciais periodicamente.
Sincronize o relógio dos servidores (expiração depende do horário correto).
Erros comuns
401 Unauthorized: token ausente, inválido ou expirado.
403 Forbidden: token inválido, mas sem escopo/permissão para o recurso solicitado.
curl --location --request POST 'https://sandbox.bigools.com.br/auth/token' \
--header 'tenant_id;' \
--header 'subscription_id;' \
--header 'user_id;' \
--header 'user_secret;'
{
"token_type": "string",
"access_token": "string",
"expires_in": 0
}