> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/autenticacao-oauth2.md). # 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. {% hint style="warning" %} 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). {% endhint %} *** ### 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.** {% hint style="warning" %} **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. {% endhint %} ### 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: {% tabs %} {% tab title="🧪 Ambiente de Testes (Sandbox)" %} ```http https://auth-sandbox.first-tech.net/oauth/token ``` {% endtab %} {% tab title="🚀 Ambiente de Produção" %} ```http https://auth.first-tech.net/oauth/token ``` {% endtab %} {% endtabs %} ### 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 {% hint style="warning" %} **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. {% endhint %} ### 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. {% tabs %} {% tab title="cURL" %} ```bash curl --request POST \ --url https://auth.first-tech.net/oauth/token \ --header 'Content-Type: application/json' \ --data '{ "client_id": "SEU_CLIENT_ID_AQUI", "client_secret": "SEU_CLIENT_SECRET_AQUI", "audience": "https://api.first-tech.net/hop", "grant_type": "client_credentials" }' ``` {% endtab %} {% tab title="HTTP (Raw)" %} ```http POST /oauth/token HTTP/1.1 Host: auth.first-tech.net Content-Type: application/json { "client_id": "SEU_CLIENT_ID_AQUI", "client_secret": "SEU_CLIENT_SECRET_AQUI", "audience": "https://api.first-tech.net/hop", "grant_type": "client_credentials" } ``` {% endtab %} {% endtabs %} ### 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. ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...", "token_type": "Bearer", "expires_in": 86400 } ``` {% hint style="success" %} **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*). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ftcoders.first-tech.com/landing-page/autenticacao-oauth2.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.