> 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/api-reference/chaves-de-api.md).

# Chaves de API

As Chaves de API permitem que um sistema externo use a Voa em nome da sua organização, sem compartilhar credenciais de login.

### Visão Geral

{% hint style="success" %}
Quer integrar seu sistema à Voa? Use o [Plugin](https://docs.voa.health/integracao/plugin), a forma ideal de embarcar a Voa na sua aplicação.
{% endhint %}

Toda Chave de API pertence a uma **organização** e é gerenciada em **Organização → Integrações**. Há dois tipos, identificados pelo prefixo:

| Tipo                 | Prefixo    | Quem cria                        | Age como                                                                | Uso típico                                     |
| -------------------- | ---------- | -------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------- |
| **Chave de membro**  | `sk_user_` | Qualquer membro da organização   | O membro que criou, com as mesmas permissões que ele tem na organização | Integração de um médico ou de um único usuário |
| **Chave de sistema** | `sk_org_`  | Somente a área **Administração** | Um sistema integrado; cada atendimento fica no médico do `doctor_id`    | PEP com vários médicos                         |

Nas duas, a chave vale só para a organização em que foi criada e é enviada no header `x-voa-token`.

{% hint style="info" %}
As chaves `sk_user_` criadas antes desta mudança continuam valendo, com o mesmo segredo: agora são chaves de membro da organização em que foram criadas. Chaves antigas sem prefixo continuam valendo como chaves de sistema. Nenhuma integração precisa trocar de chave.
{% endhint %}

{% hint style="danger" %}
Uma Chave de API é uma credencial de longa duração. Nunca a envie ao navegador nem a passe diretamente para `VoaPlugin.instance.init()`. Para usar o Plugin, mantenha a chave no backend e troque-a por tokens de sessão temporários conforme descrito em [Autenticação do Plugin](https://docs.voa.health/integracao/plugin/autenticacao.md).
{% endhint %}

***

### O que a Chave de API permite (e o que não permite)

O objetivo da Chave de API é permitir que seus usuários **utilizem a Voa dentro do seu sistema** — por exemplo, embarcar a Voa no seu prontuário eletrônico via [Plugin](https://docs.voa.health/integracao/plugin) para gravar atendimentos e gerar documentos.

{% hint style="warning" %}
**A Chave de API não lê dados.** Leitura e criação de documentos só via [MCP](https://docs.voa.health/integracao/mcp.md), com autorização do médico.
{% endhint %}

#### Chave de membro (`sk_user_`)

* Fica presa ao vínculo de quem a criou na organização e tem **as mesmas permissões que esse membro tem nela**. Se o membro não pode gravar algo na Voa, a chave também não pode.
* Vale **enquanto o dono for membro da organização**. Se ele sair ou perder o acesso, a chave e os tokens de sessão emitidos com ela passam a ser recusados (`401`, `error_code` `api_key_member_inactive`). Se o acesso voltar, a chave volta a funcionar.

#### Chave de sistema (`sk_org_`)

* É da organização, não de uma pessoa. Serve para um PEP que atende **vários médicos** com uma chave só.
* Cada atendimento fica no médico que o sistema enviar no `doctorId` do Plugin (o `doctor_id` da API). Se esse médico ainda não existir na organização, a Voa o cadastra como membro sem login.
* Só a área **Administração** da organização cria chaves de sistema.

***

### Criando uma Chave de API

#### Passo 1: Acesse as Integrações da organização

1. Faça login na plataforma Voa em [app.voa.health](https://app.voa.health/)
2. No menu lateral esquerdo, clique no ícone de **Configurações** (engrenagem)
3. Em **Organização**, selecione **Integrações**

#### Passo 2: Crie uma nova chave

1. Na seção **Chaves de API**, clique em **Nova chave**
2. Digite um **nome descritivo** para a chave
   * Exemplo: `Integração com sistema X`, `Meu App de Prontuário`, `PEP da clínica`
3. Escolha o tipo:
   * **Membro**: a chave terá as mesmas permissões que você tem nesta organização, enquanto você for membro dela.
   * **Sistema**: chave da organização para um sistema integrado (PEP); cada atendimento fica no médico que o sistema enviar. Só aparece para quem é da área **Administração**.
4. Confirme a criação

#### Passo 3: Copie e guarde a chave

{% hint style="warning" %}
**Importante:** A chave completa será exibida **apenas uma vez**, imediatamente após a criação. Copie e guarde em um local seguro. Não será possível visualizá-la novamente.
{% endhint %}

Copie a chave e armazene-a em um gerenciador de senhas ou cofre de segredos do seu backend.

***

### Gerenciando as chaves

#### Visualizando chaves existentes

Em **Organização → Integrações**, todo membro vê as chaves da organização, com:

| Informação     | Descrição                                                                       |
| -------------- | ------------------------------------------------------------------------------- |
| **Nome**       | O nome descritivo definido na criação                                           |
| **Tipo**       | Membro (`sk_user_`) ou Sistema (`sk_org_`)                                      |
| **Prefixo**    | O início da chave, para identificá-la sem expor o segredo                       |
| **Dono**       | O membro dono da chave de membro, e se ele ainda é membro; "Sistema" nas demais |
| **Último uso** | Quando a chave foi utilizada pela última vez                                    |

#### Revogando uma chave

* **Chave de membro:** o próprio dono ou a área **Administração** pode revogar.
* **Chave de sistema:** só a área **Administração** pode revogar.

A opção **Revogar** aparece apenas nas chaves que você pode revogar.

{% hint style="danger" %}
A revogação é **permanente** e vale na hora: a chave, a emissão de novos tokens de sessão e os tokens já emitidos com ela passam a ser recusados (`401`). Confirme que nenhum sistema ainda depende da chave antes de revogá-la.
{% endhint %}

***

### Boas Práticas de Segurança

#### Armazenamento seguro

* **Nunca** exponha suas chaves em código-fonte público (GitHub, GitLab, etc.)
* **Nunca** inclua chaves em HTML, JavaScript, bundles, aplicativos cliente ou armazenamento do navegador
* Utilize **variáveis de ambiente** ou **cofres de segredos** (como AWS Secrets Manager ou HashiCorp Vault) no backend
* Para o Plugin, exponha ao navegador apenas tokens de sessão temporários; veja [Autenticação do Plugin](https://docs.voa.health/integracao/plugin/autenticacao.md)

#### Rotação de chaves

* Crie novas chaves periodicamente e substitua as antigas
* Após a troca, revogue a chave anterior para prevenir novos acessos não autorizados
* Recomendamos rotacionar suas chaves a cada **90 dias**

#### Princípio do menor privilégio

* Prefira a chave de membro quando a integração é de um único médico: ela nunca pode mais do que ele
* Use a chave de sistema só para sistemas que atendem vários médicos
* Crie chaves separadas para cada serviço ou integração, com nomes descritivos (ex.: `PEP - Produção`, `App Mobile - Produção`)
* Revogue chaves que não estão mais em uso

#### Monitoramento

* Acompanhe a **data do último uso** de cada chave em **Organização → Integrações**
* Se notar uso anômalo, revogue a chave imediatamente e crie uma nova
* Verifique periodicamente se há chaves não utilizadas ou de membros que saíram

***

### Suporte

Para dúvidas ou problemas com chaves de API, entre em contato:

* **Email:** <integration@voahealth.com>
* **Documentação geral:** [docs.voa.health](https://docs.voa.health/)
