> For the complete documentation index, see [llms.txt](https://docs.veilio.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veilio.xyz/documentation/great-to-know/security-bp.md).
# Security Best Practices
## Security Best Practices
Production security guidelines for integrating Veilio.
***
#### Key management
* Use **one API key per environment** (`dev`, `staging`, `prod`)
* Use **MIGRATION** keys only for historical imports — rotate or revoke after migration completes
* Rotate keys periodically (quarterly recommended)
* Revoke unused or compromised keys immediately from **Dashboard → API Keys**
***
#### Secret handling
* Store keys in a **secrets manager** (AWS Secrets Manager, GCP Secret Manager, Vault) or secure environment variables
* Never hardcode keys in source code or commit them to Git
* Never expose API keys in browser bundles, mobile apps, or client-side JavaScript
* Restrict CI/CD secrets to deployment pipelines only
***
#### Access control
* Call Veilio **from your backend only** — the API key must never reach end-user devices
* Restrict detokenization to authorized services and user roles in your application
* Require a business **`reason`** on every detokenization call (enforced by Veilio audit logs)
* Use **column policies** on datasets to limit which roles can download which fields
* Assign **VIEWER** role only to users who must not tokenize or shred
***
#### Data handling
* **Store tokens by default**, not raw PII
* Detokenize only at the **last possible moment** in a workflow (send email, generate PDF, open support ticket)
* **Never** detokenize on page load to display raw data in the browser
* Avoid writing detokenized values to application logs, APM traces, or error reports
* Mask tokens in UI when full value is not needed (`tok_abc1...`)
***
#### Reliability and abuse protection
* Implement retries with backoff for `429` responses (SDKs do this automatically)
* Add alerts for repeated `401`, `403`, and `5xx` from your integration
* Monitor request volumes by environment and API key
* Use **bulk endpoints** for imports to reduce request count and rate-limit risk
***
#### Retention and erasure
* Set `retention.ttlDays` or `retentionUntil` at tokenization for time-limited data
* Call `POST /tokens/shred` (or `shredToken` / `shred_token`) on GDPR deletion requests
* Document your data retention policy and align TTLs with legal requirements
* Test shredded tokens return HTTP `410` (`TOKEN_SHREDDED`) — your app must handle this gracefully
***
#### Encryption and architecture
| Layer | Protection |
| ---------- | ----------------------------------------------------------------------- |
| In transit | TLS 1.2+ (HTTPS only in production) |
| At rest | AES-256-GCM for token payloads; separate platform and clients databases |
| Search | HMAC-SHA256 blind index (no plaintext stored for lookup) |
| Erasure | Cryptographic shredding — encryption keys destroyed per token |
Veilio SaaS runs on isolated infrastructure. **On-premise** deployments keep all tokenized data on your servers — Veilio never receives your business data.
***
#### Network (on-premise)
* Terminate TLS at a reverse proxy (nginx, Traefik, Caddy) in front of the Veilio container
* Restrict inbound access to trusted networks or VPN
* Allow outbound HTTPS only if using automatic license refresh or update banner
* Back up `ENCRYPTION_KEY` and PostgreSQL volumes off-server (see Installation guide)
***
#### Compliance and audit
* Enable SIEM integration for centralized audit on Enterprise / on-premise
* Export audit logs periodically via dashboard compliance tools
* Use offboarding workflow for structured account exit and data portability
* Run dump compliance checks before sharing database exports
***
#### Trust and legal
For DPA, subprocessors list, and security questionnaires, contact or .
{% hint style="info" %}
Questions or suggestions?
{% endhint %}
