Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

1. Gerar um token de sessão no backend

Faça a troca somente no backend da sua aplicação:

Resposta:

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):

  • 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(); 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:

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.

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:

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.

Atualizado