> ## Documentation Index > Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Segurança > Como a Vendaze API foi projetada para ser segura e o que isso significa para sua integração. 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](/pt/guides/authentication) e [Registre seu aplicativo](/pt/guides/register-app). ## 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](/pt/guides/rotate-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. Armazenamento de tokens, fluxo de renovação e revogação. Entrega de credenciais e a janela de 15 minutos. Quando e como rotacionar o client\_secret. Limites por método e tipo de endpoint. ## 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