Segurança

Esta página explica as decisões de segurança incorporadas na própria Vendaze API: por que foram tomadas, o que protegem e o que significam para sua integração. Práticas operacionais como armazenamento de tokens e rotação de credenciais estão em Autenticação e Registre seu aplicativo.

​

Modelo de autorização

A Vendaze API usa OAuth 2.1 Authorization Code flow com client_secret. Isso significa:

• Seu app é um cliente confidencial. Ele tem um client_secret que precisa ficar no seu servidor.
• Todas as trocas de token acontecem server-side. O browser nunca toca em um token diretamente.
• Usuários autorizam acesso a um workspace específico. Seu token tem escopo apenas para aquele workspace.

Esta não é uma integração para SPAs, apps mobile sem back-end, ou qualquer ambiente onde o usuário final possa inspecionar o código em execução. Se seu app não tem componente server-side, você precisa construir um antes de integrar.

​

PKCE é gerenciado internamente

OAuth 2.1 recomenda PKCE (Proof Key for Code Exchange) para todos os fluxos de autorização. A Vendaze API implementa PKCE, mas o gerencia inteiramente no lado do servidor. Sua integração não precisa gerar ou enviar um code_verifier. Veja o que acontece quando um usuário autoriza seu app:

1. Seu servidor redireciona o browser para /oauth/authorize com client_id, redirect_uri, response_type=code e state
2. A Vendaze API gera e gerencia os parâmetros PKCE internamente
3. Após o usuário aprovar, o authorization_code é retornado para sua redirect_uri
4. Quando você chama /oauth/token, a API completa a troca PKCE de forma transparente

O que isso protege: se um atacante interceptar o authorization_code em trânsito, ele não consegue trocá-lo por tokens. A verificação PKCE acontece server-side e nunca é exposta. Combinado com a validação do client_secret, duas provas de identidade independentes são necessárias para completar a troca. Por que você não gerencia: PKCE foi criado para clientes públicos (apps mobile, SPAs) que não conseguem armazenar um client_secret com segurança. Para clientes confidenciais como o seu, o client_secret já fornece proteção equivalente. Expor parâmetros PKCE aos integradores adicionaria complexidade sem adicionar segurança. A Vendaze API cuida disso internamente para que o fluxo de autorização permaneça limpo e compatível com qualquer biblioteca OAuth padrão.

​

Validação de tokens é assimétrica

Access tokens são assinados usando criptografia assimétrica. A API verifica cada token contra uma chave pública. Não existe segredo compartilhado envolvido na validação de tokens. Isso significa:

• Não existe chave simétrica que pudesse ser vazada e usada para forjar tokens
• Apenas o servidor de autorização pode emitir tokens válidos
• Rotação de chaves no servidor de autorização não requer nenhuma mudança na sua integração

Toda requisição para /v1/* valida presença, expiração, assinatura e claims de workspace do token antes de qualquer lógica de negócio ser executada. Um token revogado é invalidado imediatamente e não pode ser usado novamente, mesmo que ainda não tenha expirado.

​

O authorization_code é de uso único e curta duração

Códigos de autorização expiram em 10 minutos e só podem ser usados uma vez. Após uma troca bem-sucedida de tokens, o code é consumido e não pode ser reutilizado.

​

O client_secret nunca é retornado em nenhuma resposta

O client_secret é gerado uma vez e entregue exclusivamente via link seguro enviado para o e-mail cadastrado. O link expira em 15 minutos e é invalidado na primeira visualização. Ele nunca é:

• Retornado em nenhum body de resposta da API
• Logado pela API
• Acessível após a janela de entrega inicial

Se o link expirar antes de você abri-lo, você precisa rotacionar as credenciais para receber um novo. Veja Rotacionar credenciais do app.

​

Rotação de credenciais usa e-mail, não client_secret

Para rotacionar credenciais, você envia client_id e o e-mail cadastrado. O client_secret não é necessário. Esta é uma decisão de segurança intencional. Se o client_secret for comprometido, exigi-lo para rotação daria ao atacante que já tem o secret o poder de rotacionar e tomar controle do app. O e-mail cadastrado nunca é retornado por nenhum endpoint da API. Apenas a Vendaze e o dono legítimo sabem qual é. Mesmo que um atacante tenha o client_id (que é público) e descubra o e-mail, o novo client_secret nunca aparece na resposta: ele é enviado como link de uso único para aquele e-mail. Para completar a rotação, o atacante precisaria de acesso à caixa de entrada do e-mail cadastrado, o que está fora do escopo do que a API pode proteger.

​

workspace_id vem do token, nunca da requisição

O contexto de workspace de toda chamada à API é extraído dos claims do access_token. Sua integração nunca envia um identificador de workspace em parâmetros, headers ou body da requisição. Isso significa:

• Um integrador não consegue acessar dados de um workspace para o qual não foi autorizado, mesmo que conheça o workspace ID
• Não existe forma de escalar acesso manipulando parâmetros da requisição
• O isolamento multi-tenant é aplicado no nível do token, não no nível da aplicação

​

Rate limiting é em camadas

Duas camadas independentes de rate limiting se aplicam: Por IP (endpoints OAuth): /oauth/authorize, /oauth/token, /oauth/revoke e /v1/auth/* são limitados por endereço IP. Por client_id (endpoints de recursos): todos os endpoints /v1/* são limitados pelo client_id extraído do token. Os limites variam por método HTTP: 1.000 req/min para GET, 200 req/min para POST/PATCH, 100 req/min para DELETE. Esse layering significa que um token comprometido tem um raio de impacto limitado. Um atacante não consegue usar um único token para esgotar a API para outros integradores.

​

O que isso significa para sua integração

O modelo de segurança acima define um limite claro de responsabilidade: A API cuida de: PKCE, assinatura e verificação assimétrica de tokens, isolamento de workspace, revogação de tokens, rate limiting, segurança na entrega de credenciais. Você cuida de: armazenar o client_secret em um gerenciador de segredos, armazenar tokens criptografados server-side, validar o parâmetro state no callback OAuth, revogar tokens quando usuários desconectam, rotacionar credenciais se comprometidas.

​

Resposta a incidentes

Se suspeitar de comprometimento do client_secret ou de tokens:

• Revogue todos os tokens ativos via POST /oauth/revoke para cada workspace afetado
• Rotacione as credenciais imediatamente via POST /v1/auth/rotate-app
• Atualize seu gerenciador de segredos com o novo client_secret
• Entre em contato com security@vendaze.com com o request_id de requisições suspeitas
• Notifique os usuários afetados que precisam re-autorizar
• Revise seus logs para identificar acesso não autorizado durante a janela de exposição