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:
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 com401(error_codeapi_key_member_inactive).Chave de sistema (
sk_org_): o token age como o sistema integrado. Cada atendimento fica no médico dodoctorIdpassado aomount(); odoctor_iddo 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
getTokendeve retornar umaPromise<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
401ou403de 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
getTokentem limite de 10 segundos. Falhas, timeout ou token vazio encerram a autenticação e disparam o eventovoa.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