Autenticação (OAuth2)
Visão Geral
A segurança é a base do HoP API v4. Como lidamos com operações criptográficas e dados sensíveis, todas as requisições aos nossos serviços devem ser obrigatoriamente autenticadas.
Para facilitar sua integração e garantir o mais alto nível de segurança, utilizamos o padrão de mercado OAuth2 (gerenciado via Auth0).
Nesta seção, você aprenderá como obter suas credenciais, gerar um token de acesso (access_token) e como enviá-lo corretamente no cabeçalho das suas requisições.
Atenção: Suas credenciais (client_secret) e seus tokens de acesso dão poder total sobre o seu ambiente criptográfico. Nunca exponha esses dados no front-end (navegadores ou aplicativos móveis) ou em repositórios públicos (como o GitHub).
O Protocolo OAuth2 (M2M)
A HoP API v4 utiliza o padrão OAuth2 através do fluxo de Client Credentials (Credenciais de Cliente).
Como a nossa infraestrutura foi desenhada para operações de backend (comunicação de servidor para servidor), este é o fluxo ideal para interações Máquina-a-Máquina (M2M). Ele permite que a sua aplicação se autentique de forma autônoma e contínua, sem a necessidade de intervenção humana (como telas de login de usuários).
Essa abordagem garante o isolamento total da sua aplicação e a proteção dos dados durante operações criptográficas críticas, mantendo a sua integração em total conformidade com as normas de segurança do mercado.
Obtenção de Credenciais (Webadmin)
Para se comunicar com a HoP API, sua aplicação precisará de duas chaves exclusivas: um Client_Id e um Client_Secret.
Por questões de segurança e controle de acesso, essas credenciais não são geradas dinamicamente via API.
Pré-requisito Obrigatório: Antes de prosseguir com qualquer teste ou integração, acesse a plataforma Webadmin (nosso portal de gestão de chaves) para provisionar e validar as suas credenciais. A geração do token de acesso não funcionará sem este passo.
Endpoints de Autenticação (Auth0)
Para gerar o seu token de acesso, você fará uma requisição POST para o nosso servidor de autorização.
Lembre-se da regra de ouro: as credenciais geradas no Webadmin de Sandbox só funcionam na URL de Sandbox, e as credenciais do Webadmin de Produção só funcionam na URL de Produção.
Utilize o endpoint correspondente ao seu ambiente:
Parâmetros da Requisição (Payload)
A solicitação do token deve ser enviada via método POST. O corpo da requisição (body) deve conter os seguintes parâmetros no formato JSON:
client_id · string · Obrigatório
O identificador único da sua aplicação. Você deve obter este valor no painel do Webadmin.
client_secret · string · Obrigatório
A chave secreta da sua aplicação, também obtida no Webadmin. Nunca exponha este valor.
audience · string · Obrigatório
O identificador único do recurso (API) que você deseja acessar.
grant_type · string · Obrigatório
Define o fluxo de autenticação. Para interações máquina-a-máquina, deve ser estritamente
Atenção ao campo audience
O valor deste campo muda de acordo com o ambiente. Se você usar o audience de Sandbox apontando para a URL de Produção (ou vice-versa), o Auth0 emitirá um token inválido e suas chamadas ao HoP API serão rejeitadas. Confirme o valor correto no Webadmin.
Exemplo de Requisição
Abaixo, apresentamos a estrutura da chamada. Lembre-se de configurar o cabeçalho Content-Type como application/json e substituir os valores de exemplo pelas suas credenciais reais obtidas no painel do Webadmin.
Resposta de Sucesso
Se as credenciais estiverem corretas, o servidor retornará um status 200 OK. O corpo da resposta conterá o seu token de acesso (JWT) e o tempo de validade dele em segundos.
Melhor Prática: Faça cache do seu Token
Para garantir altíssimo desempenho e evitar latência nas suas transações, não gere um novo token a cada requisição.
O valor retornado em expires_in (ex: 86400 segundos = 24 horas) indica quanto tempo essa chave é válida. A estratégia correta é salvar o access_token na memória da sua aplicação (cache) e reutilizá-lo em todas as chamadas ao HSM, solicitando um token novo apenas quando o atual estiver a poucos minutos de expirar. Isso também evita que você seja bloqueado por excesso de chamadas (Rate Limiting).
Last updated