> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Segurança
> Como certificados, API Keys e dados fiscais são protegidos em trânsito, em repouso e por isolamento entre parceiros.
A engineAPI lida com dados fiscais sensíveis e certificados digitais. Segurança é levada a sério em todas as camadas da infraestrutura.
TLS 1.3 em trânsito, AES-256 em repouso
Dados segregados por Partner e Issuer
Aderência à LGPD e padrões fiscais
***
## Certificados digitais
### Armazenamento seguro
Os certificados A1 (.pfx) dos seus clientes são tratados com o mais alto nível de proteção:
| Aspecto | Implementação |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Upload | Via HTTPS (TLS 1.3). Certificado nunca trafega em texto plano |
| Armazenamento | Encriptado com AES-256 usando chave rotacionada |
| Acesso | Somente o serviço de emissão fiscal acessa o certificado, em memória |
| Exposição | A API nunca retorna o conteúdo do certificado, apenas metadados |
| Substituição | Não existe endpoint para remover só o certificado. Um novo upload via `POST /v1/companies/:id/certificate` substitui o anterior |
| Remoção total | `DELETE /v1/companies/:id` remove a empresa inteira, incluindo o certificado |
Certificados A1 são arquivos sensíveis. Nunca armazene a senha do certificado em código-fonte, logs ou variáveis de ambiente expostas. Use um vault de secrets dedicado.
### Validade e renovação
```bash theme={null}
curl https://api.engineapi.com.br/v1/companies/ISSUER_UUID \
-H "Authorization: Bearer SEU_JWT"
# → { "data": { "certExpiry": "...", ... } }
```
Desde `@engineapi/sdk@1.1.0`, `client.companies.*` chama as rotas reais (`/companies`)
e envia o certificado como multipart/form-data. Pode usar o SDK ou chamadas REST
diretas como acima. Detalhe em [SDK TypeScript](/sdks/typescript#companies-empresas-emissoras).
Configure um webhook para ser notificado quando um certificado está próximo do vencimento: ver [Certificado digital](/guides/certificates#monitorando-a-validade).
***
## Autenticação
### API Keys
| Característica | Implementação |
| -------------- | ------------------------------------------------- |
| Formato | `ek_live_UUID` (prefixo identificável) |
| Hash | Armazenada como hash bcrypt. Impossível recuperar |
| Rotação | Crie quantas keys quiser, revogue as antigas |
| Exposição | O valor completo é mostrado apenas na criação |
```bash theme={null}
# Regenerar API Key (revoga a anterior)
curl -X POST https://api.engineapi.com.br/v1/auth/api-keys/regenerate \
-H "Authorization: Bearer SEU_JWT"
# → { "apiKey": "ek_live_..." } (único momento em que a chave completa aparece)
```
### JWT (sessões de dashboard)
| Característica | Implementação |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| Algoritmo | HS256 com secret rotacionado |
| Expiração do access token | 12 horas |
| Refresh token | 30 dias, rotacionado a cada uso (o antigo morre na hora) |
| Logout | Revoga a sessão no servidor: o access token para de valer imediatamente, não só quando expira |
| Troca de senha | Derruba **todas** as sessões abertas da conta |
### Verificação em duas etapas (2FA)
| Característica | Implementação |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| Padrão | TOTP (RFC 6238), 6 dígitos, passo de 30 s, tolerância de ±1 passo |
| Obrigatória para | Superadmin da plataforma e dono de parceiro (`PartnerMember.role = OWNER`) |
| Opcional para | Demais usuários (ligável em Configurações → Segurança) |
| Segredo | Cifrado em repouso (AES-256-GCM) com a chave amarrada ao usuário; exibido uma única vez, no enrolamento |
| Códigos de recuperação | 10 por enrolamento, uso único, guardados só como hash SHA-256 |
| Reuso de código | Recusado: o mesmo código de 30 s não vale duas vezes |
O SSO Google **não** é atalho: quem é obrigado a ter segundo fator passa pelo
mesmo portão ao entrar pelo Google.
### Bloqueio por tentativas de login
| Característica | Implementação |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Escopos | Por e-mail e por IP, independentes |
| Escada (e-mail) | 5 falhas → 1 min · 10 → 15 min · 15 → 1 h · 20 → 4 h |
| Durante o bloqueio | A senha correta também é recusada |
| Resposta | Sempre `401 Credenciais inválidas`: bloqueio, senha errada e e-mail inexistente são indistinguíveis (anti-enumeração) |
| Esquecimento | Balde sem falha nova por 1 hora zera sozinho |
### Alertas de segurança por e-mail
O titular da conta (e o dono da plataforma, quando configurado) recebe e-mail
a cada **login de superadmin**, **troca de senha**, **mudança de 2FA** e **uso
de código de recuperação**. O alerta traz quando, de onde e por qual navegador;
nunca carrega senha, código ou token.
***
## Infraestrutura
### Práticas de segurança
A engineAPI segue estas práticas em toda a infraestrutura, independente da tecnologia por
trás:
| Prática | O que garante |
| ---------------------------------- | ----------------------------------------------------------------------- |
| Transporte encriptado | TLS 1.2+ em toda comunicação, com HSTS e rate limiting na borda |
| Certificados em repouso | Certificados A1 encriptados com chave rotacionada, nunca em texto plano |
| Isolamento por tenant | Dados segregados por Partner e Issuer, sem vazamento entre contas |
| Validação estrita em cada endpoint | Payload fora do contrato é recusado com mensagem de erro estruturada |
| Menor privilégio | Cada componente acessa só o que precisa para operar, nada além disso |
| Monitoramento 24/7 | Rastreamento de erros e métricas de disponibilidade em tempo real |
### Headers de segurança
Todas as respostas incluem estes headers de segurança:
```
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 0
Content-Security-Policy: default-src 'self'
Referrer-Policy: strict-origin-when-cross-origin
```
***
## LGPD e proteção de dados
### Dados coletados
| Dado | Propósito | Retenção |
| -------------- | ------------------------------------ | ------------------------------ |
| CNPJ/CPF | Emissão fiscal (obrigatório por lei) | Enquanto a conta estiver ativa |
| Certificado A1 | Assinatura digital junto à SEFAZ | Até remoção pelo partner |
| Endereços | Composição do XML fiscal | Enquanto a conta estiver ativa |
| Logs de acesso | Auditoria e troubleshooting | 90 dias |
### Direitos do titular
| Direito | Como exercer |
| ------------- | ------------------------------------------------- |
| Acesso | `GET /v1/companies/:id` retorna todos os dados |
| Correção | `PATCH /v1/companies/:id` atualiza dados |
| Exclusão | `DELETE /v1/companies/:id` remove empresa e dados |
| Portabilidade | Download de XMLs via endpoints de download |
A engineAPI atua como **operadora** de dados. O Partner (Software House) é o **controlador** perante a LGPD. O Partner é responsável por obter consentimento do titular antes de enviar dados para a API.
***
## Boas práticas
* Nunca exponha a API Key em código frontend
* Use variáveis de ambiente no servidor
* Rotacione keys periodicamente
* Revogue keys comprometidas imediatamente
* Verifique a validade do certificado (.pfx) antes de enviar
* Configure alertas para certificados próximos do vencimento
* Mantenha um processo de renovação documentado
* Acompanhe o consumo via dashboard
* Configure webhooks para eventos de erro
* Use os headers `X-RateLimit-*` para evitar throttling
* Sempre teste em homologação antes de ir para produção
* Use dados fictícios em testes
* Nunca use certificados de produção em homologação
***
## Registro de acesso e alertas
Toda chamada autenticada entra na trilha de auditoria do seu parceiro com o
endereço de origem, e é esse endereço que aparece no painel e nos alertas de
segurança da EngineAPI.
O endereço é resolvido a partir de `X-Engine-Client-IP`, `X-Forwarded-For` e
`X-Real-IP`, mas **apenas quando esses cabeçalhos chegam pelo gateway da
EngineAPI**. Se a sua integração enviar um deles numa chamada direta, o valor é
descartado e vale o endereço real da conexão: não é possível escolher qual IP
aparece na sua auditoria.
Se você chama a EngineAPI através de um proxy próprio (NAT, saída fixa, gateway
corporativo), o endereço registrado é o de saída desse proxy, não o da máquina
interna.
### O que dispara alerta
Estas situações avisam a equipe da EngineAPI na hora, mesmo quando a chamada é
sua e legítima. **Nenhuma delas bloqueia a chamada.**
| Situação | Limiar |
| ------------------------------------------------ | --------------- |
| Respostas `401`/`403` do mesmo endereço | 20 em 5 minutos |
| Cadastros criados do mesmo endereço | 3 em 1 hora |
| `PATCH /v1/webhooks/config` (destino do webhook) | toda vez |
| `POST /v1/webhooks/secret/regenerate` | toda vez |
| Regeneração de chave de API | toda vez |
Se a sua esteira de testes costuma bater em `401` em série, use a chave
`ek_test_` e trate o erro em vez de repetir a tentativa em laço.
***
## Veja também
* **[Rate limits](/guides/rate-limits):** limites de uso e como evitar throttling.
* **[Multi-tenancy](/guides/multitenancy):** arquitetura B2B2B e isolamento de dados.