> For the complete documentation index, see [llms.txt](https://docs.voa.health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voa.health/integracao/plugin/autenticacao.md). # Autenticação Mantenha a Chave de API no backend e autentique o Plugin no navegador com tokens de sessão temporários. ## Visão geral A **Chave de API** é uma credencial de longa duração e deve permanecer no backend da sua aplicação. Para autenticar o Plugin no navegador, seu backend troca essa chave por um **token de sessão temporário** e entrega apenas o token ao frontend. {% hint style="danger" %} Nunca coloque uma Chave de API no HTML, JavaScript, bundle da aplicação, armazenamento do navegador ou chamada feita diretamente pelo frontend. Qualquer pessoa com acesso à página pode recuperar essa credencial. {% endhint %} ```mermaid sequenceDiagram participant Frontend as Seu frontend participant Backend as Seu backend participant VoaAPI as API da Voa participant Plugin as Plugin Voa Frontend->>Backend: Solicita token de sessão Backend->>Backend: Autentica e autoriza o usuário Backend->>VoaAPI: POST /integration/session-token/ com x-voa-token VoaAPI->>Backend: access + access_expiration Backend->>Frontend: Retorna o token temporário Frontend->>Plugin: getToken() retorna access Plugin->>VoaAPI: Authorization: Bearer access ``` ## 1. Gerar um token de sessão no backend Faça a troca somente no backend da sua aplicação: ```bash curl --request POST \ --url https://api.voa.health/integration/session-token/ \ --header 'Content-Type: application/json' \ --header 'x-voa-token: {SUA_CHAVE_DE_API}' \ --data '{ "expiration": 1800 }' ``` Resposta: ```json { "access": "{TOKEN_DE_SESSAO}", "access_expiration": "2026-08-27T14:00:00+00:00" } ``` | Campo | Obrigatório | Descrição | | ------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `expiration` | Não | Validade em segundos. Mínimo de 1.800 (30 minutos), máximo de 86.400 (24 horas) e padrão de 43.200 (12 horas). Recomendamos 1.800. | | `doctor_id` | Não | Identificador informativo para auditoria. Não limita o token a esse médico. Máximo de 255 caracteres. | O token é vinculado à organização associada à Chave de API. Seu endpoint deve autenticar o usuário da aplicação host e confirmar que ele pode usar essa organização antes de solicitar ou retornar um token. Não transforme o endpoint em um relay público. ## 2. Disponibilizar um endpoint no seu backend Crie um endpoint autenticado da sua aplicação, por exemplo `POST /api/voa/session-token`, que execute a troca acima e retorne o campo `access`. Armazene a Chave de API em uma variável de ambiente ou cofre de segredos do backend. O navegador deve chamar apenas esse endpoint próprio: ```javascript async function getVoaSessionToken() { const response = await fetch("/api/voa/session-token", { method: "POST", credentials: "include", headers: { "Content-Type": "application/json" } }); if (!response.ok) { throw new Error("Não foi possível autenticar o Plugin Voa"); } const { access } = await response.json(); return access; } ``` ## 3. Inicializar o Plugin com `getToken` Passe a função ao `init`. O Plugin obtém o primeiro token e solicita outro quando o token expira ou é rejeitado pela API. ```javascript VoaPlugin.instance.init({ getToken: getVoaSessionToken }); ``` Se sua página já recebeu um token de sessão temporário, ele pode ser usado como valor inicial. O `getToken` continua responsável pelas renovações: ```javascript VoaPlugin.instance.init({ token: initialSessionToken, getToken: getVoaSessionToken }); ``` Também é possível inicializar somente com `{ token: sessionToken }`, mas esse modo não renova a sessão. Quando o token expirar ou for rejeitado, o Plugin encerra a autenticação. Use `getToken` para sessões que podem permanecer abertas por mais tempo. ## Comportamento de renovação * `getToken` deve retornar uma `Promise` com um token de sessão válido e não vazio. * O Plugin chama o provider na inicialização quando não há token inicial, antes de uma requisição com token expirado e após uma resposta `401` ou `403` de autenticação. * Requisições simultâneas compartilham a mesma renovação em andamento, evitando múltiplas emissões do mesmo token. * Uma requisição rejeitada é repetida no máximo uma vez com a credencial atualizada. * Cada chamada a `getToken` tem limite de 10 segundos. Falhas, timeout ou token vazio encerram a autenticação e disparam o evento `voa.plugin.error.auth`. * `unmount()` remove o provider e invalida renovações ainda em andamento. ## Revogação e validade Excluir a Chave de API impede imediatamente a emissão de novos tokens de sessão. Tokens já emitidos permanecem válidos até `access_expiration`; por isso, prefira a validade mínima de 30 minutos. Desativar o usuário vinculado invalida seus tokens de sessão imediatamente. Para reduzir exposição, mantenha o token de sessão apenas em memória sempre que possível e nunca registre Chaves de API ou tokens completos em logs. --- # 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://docs.voa.health/integracao/plugin/autenticacao.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.