Historical Migration Mode
Import a large existing database (e.g. 150k contacts from a CRM export) without consuming your monthly plan quota. Migration mode gives you a one-shot token budget for historical imports only.
When to use it
| Scenario | Use migration mode? |
|---|---|
| One-time CSV/JSON import of historical PII | ✅ Yes |
| Ongoing tokenization in production (forms, APIs) | ❌ No — use a standard API key |
| GDPR full export when leaving Veilio | ❌ No — export is already quota-free |
How it works
- Activate migration from the dashboard (
/dashboard/onboarding→ « Migration mode » card, orPOST /api/onboarding/migration). - Veilio creates a one-shot budget on your subscription:
migrationAllowance,migrationTokensUsed,migrationExpiresAt. - A dedicated API key with
purpose = MIGRATIONis generated (shown once). - Requests signed with this key (or dataset uploads with
migration=true) consume the migration budget, not monthly tokens/requests. - When the budget is exhausted or expired, migration calls are rejected explicitly (no silent fallback to monthly quota).
Option A — Reusable script (veilio-migrate.mjs)
Download from your app (no login required):
bash
curl -O https://app.veilio.fr/veilio-migrate.mjsRun on a CSV export:
bash
export VEILIO_API_KEY="sk_..._MIGRATION_KEY"
export VEILIO_BASE_URL="https://app.veilio.fr"
node veilio-migrate.mjs \
--in customers.csv \
--out customers.tokenized.csv \
--columns email,phone,full_name \
--types email=email,phone=phone \
--entity-id-col customer_id \
--retention-days 3650 \
--batch 100 \
--resume| Flag | Description |
|---|---|
--columns | Comma-separated sensitive columns to tokenize |
--types | Optional col=type mapping (email, phone, …) |
--entity-id-col | Business id column kept in clear (for entityId / profile grouping) |
--resume | Resume from last checkpoint after interruption |
--dry-run | Parse only, no API calls |
The script uses POST /api/tokenize/bulk with your migration key and backs off on HTTP 429.
Option B — Dataset upload (dashboard)
- Create an organization (required for team sharing; optional for solo import).
- Upload CSV/JSON from Datasets with migration mode enabled (
migration=trueon the upload API). - Cell count is debited from the migration budget after successful tokenization.
API behaviour with a migration key
| Endpoint | Monthly quota | Migration budget |
|---|---|---|
POST /tokenize, /bulk, /format | Skipped | Consumes tokens created |
POST /flows/ingest | Skipped | Consumes tokens created |
POST /detokenize (migration key) | Skipped | Not consumed (no new tokens) |
POST /datasets with migration=true | Skipped | Consumes tokenized cells |
Standard keys (purpose = STANDARD) always use monthly plan limits.
Check migration status
Authenticated dashboard or API:
bash
GET /api/onboarding/migrationResponse includes allowance, used, remaining, expiresAt, and active migration keys (prefix only).
Requirements
- Active paid plan (Starter, Pro, or Enterprise) — migration is not available on Freemium.
- Organization OWNER or DPO to activate.
- Plan your
migrationAllowanceto cover worst-case cell count (non-empty cells in the export).