> 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 da Chave de API e age conforme o tipo da chave (veja [Chaves de API](https://docs.voa.health/api-reference/chaves-de-api.md)):

* **Chave de membro (`sk_user_`):** o token age como o membro dono da chave, com as mesmas permissões que ele tem na organização. Se o dono sair da organização ou perder o acesso, a emissão e os tokens já emitidos passam a ser recusados com `401` (`error_code` `api_key_member_inactive`).
* **Chave de sistema (`sk_org_`):** o token age como o sistema integrado. Cada atendimento fica no médico do `doctorId` passado ao [`mount()`](https://docs.voa.health/integracao/plugin/fluxo-de-uso.md); o `doctor_id` do token é só informativo.

A chamada, o header `x-voa-token` e a resposta são os mesmos para os dois tipos.

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<string>` 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

Revogar a Chave de API em **Organização → Integrações** vale na hora: a emissão de novos tokens de sessão e os tokens já emitidos com ela passam a ser recusados (`401`), porque a chave é conferida a cada requisição. Numa chave de membro, a saída do dono da organização ou a perda do acesso também invalida os tokens dela imediatamente. Mesmo assim, prefira a validade mínima de 30 minutos.

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.
