> 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/sovereign-backups.md). # Sovereign backups It answers the question every CTO asks before signing: *what happens to my data if Veilio disappears?* **Who is this for?** * Teams that would lose access to their data if their own database were wiped or ransomed * Teams that need a documented exit path from Veilio (procurement, due diligence, DORA) * Anyone who wants to detokenize without depending on Veilio being online **Pro or Enterprise** plan required (or on-premise deployment). *** **What problem it solves** Tokenization splits the data from its meaning: your database holds tokens, Veilio holds the mapping. That split is the security benefit — and the availability risk. | Scenario | Without Sovereign Backup | With Sovereign Backup | | ------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------- | | Your database is wiped or encrypted by ransomware | Tokens are gone from your side | Restore tokens and values from your bundle | | Veilio is down | Detokenization unavailable until service returns | Detokenize offline, immediately | | Veilio is compromised | Attacker cannot read your bundles (they lack your private key) | Same — plus you keep an independent copy | | You leave Veilio | Requires a coordinated migration | You already hold a complete, self-describing export | *** **Security model** * The key pair is generated **in your browser**. The private key is downloaded to your machine and **never sent to Veilio**. * Veilio stores only your **public key** and its SHA-256 fingerprint. * Each bundle is encrypted with a random AES-256-GCM content key, itself wrapped with your public key using **RSA-OAEP / SHA-256**. * Veilio cannot read a bundle it just produced. A full compromise of Veilio does not expose your backups. * Destination credentials (S3 secret key, auth header) are encrypted at rest with the Veilio master key and are never returned by the API. {% hint style="warning" %} Veilio cannot recover your private key. If you lose it, existing bundles become permanently unreadable. Store it in a password manager or cold storage. {% endhint %} *** **Setup (dashboard)** 1. Sign in as the **organization Owner**. 2. Open **Dashboard → Sovereign Backup**. 3. Click **Generate my key**. Your private key (`veilio-recovery-key.pem`) downloads immediately — save it somewhere safe. 4. Verify the displayed fingerprint matches your key file. You can now use either mode — or both. **Manual export** Click **Download a backup** whenever you want. The bundle is generated on demand and downloaded through your browser. **Automatic backup** Configure a destination, run **Test**, then flip the toggle: | Destination | What you need | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **S3-compatible storage** | Endpoint, region, bucket, object key, access key ID and secret. Works with AWS S3, Cloudflare R2, Scaleway, MinIO, and Backblaze B2. Enable path-style URLs for MinIO. | | **HTTPS endpoint** | Any URL that accepts a `PUT`, with an optional auth header. Works with presigned URLs and internal storage gateways. | Each scheduled run **replaces** the previous bundle at the same location. Your backup stays current without your storage growing over time. | Plan | Minimum frequency | | -------------- | ----------------- | | **Pro** | Every 24 hours | | **Enterprise** | Hourly | On Veilio SaaS, scheduled backups run automatically — no external cron to configure. {% hint style="info" %} The connectivity **Test** writes a small `.probe` object next to your backup path. It never overwrites the live bundle. {% endhint %} *** **Bundle format** A bundle is a JSON envelope. Its metadata is readable without the private key; the payload is not. ```json { "format": "veilio.sovereign-backup", "version": 1, "createdAt": "2026-08-12T10:00:00.000Z", "organizationId": "org_...", "organizationName": "veilio", "keyFingerprint": "sha256:...", "algorithms": { "keyWrap": "RSA-OAEP-256", "content": "AES-256-GCM" }, "wrappedKey": "base64...", "payload": "base64...", "stats": { "tokenCount": 12480, "userKeyCount": 3, "truncated": false } } ``` `truncated: true` means the organization exceeded the per-bundle token cap and the bundle is incomplete. Contact if you see this. *** **Restoring offline** The restore tool runs with **no database**, **no network**, and **no Veilio account**. That is what makes the escape hatch real. ```bash # Inspect a bundle without decrypting it npx tsx scripts/sovereign-restore.ts --bundle ./backup.veiliobak --inspect # Restore to JSON npx tsx scripts/sovereign-restore.ts \ --bundle ./backup.veiliobak \ --key ./veilio-recovery-key.pem \ --out ./restored.json # Restore to CSV npx tsx scripts/sovereign-restore.ts \ --bundle ./backup.veiliobak \ --key ./veilio-recovery-key.pem \ --format csv \ --out ./restored.csv ``` The script lives in the Veilio repository at `scripts/sovereign-restore.ts`. It is intentionally self-contained (Node.js + built-in `crypto` only). Output rows contain `token`, `value`, `type`, `entityId`, and `createdAt` , enough to rebuild your mapping or reload it into another system. {% hint style="danger" %} The restored file contains **plaintext sensitive data** and is written with `0600` permissions. Delete it once you have reloaded your data. {% endhint %} *** **Rotating your key** Generating a new key does **not** invalidate old bundles: each bundle stays readable with the private key that was current when it was created. Keep your previous private keys as long as you keep the bundles they seal. Rotation pauses automatic backups so you re-enable them deliberately, after confirming the new key is safely stored. *** **Operational notes** * Only the organization **Owner** can configure Sovereign Backup or trigger an export. * Manual exports are rate-limited to **5 per hour** and recorded in your audit log as `EXPORT_BY_USER`. * Every run manual or scheduled appears in the backup history with its status, token count, size, and any error. * Shredded tokens are excluded from bundles: a Sovereign Backup never resurrects data you deleted for compliance reasons. * After a plan downgrade below Pro, automatic backups stop; existing bundles remain readable with your private key. *** {% hint style="info" %} Questions or suggestions? Contact . {% 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/sovereign-backups.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.