Autenticação e autorização do projeto

O desenvolvedor escolhe livremente o modelo do projeto. Todas as rotas podem ser públicas, algumas integrações podem exigir a chave individual e os usuários podem usar autenticação própria ou um provedor externo. A Vupi não obriga login nem obriga a existência de um backend adicional para um frontend.

Chave individual

Em Segurança do projeto, gere a única chave ativa. Ela é exibida completa uma vez e a Vupi armazena somente seu hash. Rotas marcadas com @private, @protected, @auth ou @privado exigem o cabeçalho X-API-Key. Gerar outra chave invalida a anterior; revogar bloqueia chamadas externas às rotas privadas.

Entre servidores, envie a chave somente por HTTPS e valide o certificado. O TLS protege os cabeçalhos durante o transporte; o risco restante é a chave aparecer em Git, logs, configuração exposta ou em um servidor comprometido. A Vupi guarda somente o hash, não registra a chave e remove o cabeçalho antes de encaminhar a chamada ao container. Nunca envie a chave na URL.

curl -H "X-API-Key: vpk_SUA_CHAVE" \
  https://meu-projeto.apps.seudominio.com/api/privada

Exemplo seguro em backend

Quando a chave precisa continuar secreta, guarde-a no cofre de segredos ou variável protegida do servidor. Nunca a grave no Git ou em logs. O servidor acrescenta a chave ao chamar o projeto Vupi:

const resposta = await fetch(`${process.env.PROJECT_API_URL}/tarefas`, {
  headers: { "X-API-Key": process.env.PROJECT_API_KEY }
});

Exemplo direto no frontend

O uso direto é permitido quando o desenvolvedor aceita que a chave será pública. Cadastre a origem no CORS e envie o cabeçalho normalmente:

const API_URL = "https://meu-projeto.apps.seudominio.com";
const PROJECT_API_KEY = "vpk_SUA_CHAVE";

const resposta = await fetch(`${API_URL}/tarefas`, {
  headers: { "X-API-Key": PROJECT_API_KEY }
});

A chave no frontend pode ser copiada

Qualquer visitante pode encontrá-la no bundle, no código-fonte ou no painel Network e reutilizá-la com curl, Postman ou outro programa. CORS controla a leitura por páginas no navegador, mas não torna a chave secreta, não autentica uma pessoa e não bloqueia clientes fora do navegador. Use essa opção apenas quando o risco for aceitável.

Usuários da aplicação

A chave identifica o projeto consumidor, não uma pessoa. Quando a regra exigir identidade, implemente sessão, token de usuário, OAuth/OIDC e autorização sobre cada recurso. Proteja mutações autenticadas por cookie contra CSRF e aplique rate limiting independentemente da chave.

Como testar

Teste sem chave e espere 401.
Teste chave inválida ou revogada e espere 401.
Teste a chave de outro projeto e confirme rejeição.
Teste a chave correta e verifique que a rota é executada.
Se usar frontend, teste o preflight e a origem CORS separadamente.