> 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 %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.veilio.xyz/documentation/great-to-know/security-bp.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.