Developer Platform API
Quick reference
Base URL
| Environment | URL |
|---|---|
| Production (SaaS) | https://app.veilio.fr/api |
| On-premise | https://<your-domain>/api |
| Local / dev | http://localhost:3000/api |
Use
https://app.veilio.fr/api, notapi.veilio.com.
Authentication
| Method | Header |
|---|---|
| API key (recommended) | Authorization: Bearer <API_KEY> or X-API-Key: <API_KEY> |
| Dashboard session | Cookie veilio_session |
| Dataset download | x-veilio-dataset-access-token: dsat_... |
| Public dataset link | Query ?public_token=... (one-time) |
API key purposes
| Purpose | Use |
|---|---|
STANDARD | Production tokenize / detokenize (monthly quota) |
MIGRATION | Historical import only (migration budget, not monthly quota) |
Plan quotas (SaaS)
Source of truth: product config (src/lib/stripe/plans.ts). Token ceiling is lifetime (not a monthly reset). Included requests are monthly; overage uses credits (1 credit = €0.0145). Credits plan gets 100 credits at signup.
| Plan | Tokens created (total) | Requests included / month | API keys | Datasets | Members |
|---|---|---|---|---|---|
| Credits (ex-Freemium) | No hard cap (limited by credit balance) | 0 (all on credits) | Unlimited | Unlimited | 1 |
| Starter (€29 / mo) | 2 000 lifetime | 3 000 | Unlimited | Unlimited | 2 |
| Pro (€79 / mo) | 5 000 lifetime | 10 000 | Unlimited | Unlimited | 5 |
| Enterprise | Custom | Custom | Unlimited | Unlimited | Unlimited |
A request / credit unit counts successful tokenize, detokenize, shred (and bulk cells = N units). Tokens count new tokens created in the clients database.
On-premise limits are defined in your signed license.jwt.
Core endpoints (API key)
| Method | Path | Description |
|---|---|---|
| POST | /tokenize | Single field |
| POST | /tokenize/bulk | Batch fields |
| POST | /tokenize/format | JSON / CSV / SQL in-place |
| POST | /detokenize | Reveal one token |
| POST | /detokenize/bulk | Reveal many |
| POST | /detokenize/format | Multi-format reveal |
| POST | /tokens/shred | Crypto-shred one token |
| POST | /flows/ingest | Form / lead JSON ingestion |
Detailed curl examples: HTTP Integration.
POST /tokenize
// Request
{
"data": "0612345678",
"type": "phone",
"mode": "fpt",
"entityId": "BP10042",
"retention": { "ttlDays": 365 }
}
// Response 201
{
"token": "0600000000",
"createdAt": "2026-03-26T1000.000Z",
"retentionUntil": "2027-03-26T1000.000Z"
}Omit mode, or set "standard", to receive tok_…. Names, streets, cities, amounts and invoice dates stay on that default.
POST /tokenize/bulk
// Request
{
"entityId": "BP10042",
"fields": [
{ "data": "a@example.com", "type": "email", "mode": "fpt" },
{ "data": "+336...", "type": "phone", "mode": "fpt", "retention": { "ttlDays": 30 } },
{ "data": "Ada Lovelace", "type": "firstName" }
]
}
// Response 201
{
"tokens": [
{ "token": "00000000@example.com", "type": "email", "createdAt": "...", "retentionUntil": null },
{ "token": "0600000000", "type": "phone", "createdAt": "...", "retentionUntil": "..." },
{ "token": "tok_...", "type": "firstName", "createdAt": "...", "retentionUntil": null }
],
"summary": { "total": 3, "success": 3, "failed": 0 },
"createdAt": "..."
}Two fields of the same type and the same entityId share one mask. The second clear replaces the first in the vault.
POST /detokenize/bulk
// Request
{
"entityId": "BP10042",
"reason": "Partner screen",
"tokens": [
{ "token": "00000000@example.com" },
{ "token": "0600000000" },
{ "token": "000000000", "type": "siren" }
]
}Nine zeros are both a SIREN and a postal code, so type is required.
POST /flows/ingest
// Request
{
"flowId": "signup-v1",
"source": "website",
"entityId": "lead_42",
"data": { "email": "john@example.com", "phone": "+336..." },
"metadata": {}
}
// Response 201
{
"flowId": "signup-v1",
"protectedData": { "email": "tok_...", "phone": "tok_...", "company": "Acme" },
"tokens": [{ "path": "email", "token": "tok_...", "type": "email" }],
"lookup": { "email_hash": "...", "phone_hash": "..." },
"policyApplied": "api_key_schema",
"metadata": {}
}Dashboard / session endpoints
Require an authenticated dashboard session (not an API key unless noted).
| Method | Path | Description |
|---|---|---|
| GET | /tokens | Paginated token list (RBAC) |
| DELETE | /tokens/[id] | Delete one token (session only) |
| POST | /tokens/lookup | Search by plaintext value or entityId (session only) |
| POST | /tokens/reveal-bulk | Reveal up to 100 tokens |
| POST | /tokens/shred-bulk | Shred up to 1 000 ids or one entityId (API key or session) |
| POST | /compliance/export | Start GDPR export (2FA) |
| GET | /compliance/logs-export | Download audit logs |
| GET | /compliance/offboarding/summary | Offboarding inventory |
| DELETE | /compliance/delete-account | Delete account |
| POST | /onboarding/migration | Activate migration mode |
| GET | /onboarding/migration | Migration budget status |
Datasets (hybrid auth)
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /datasets | API key or session | List datasets |
| POST | /datasets | API key or session (Owner/DPO) | Upload CSV or JSON |
| GET | /datasets/[id] | API key or session | Dataset metadata |
| GET | /datasets/[id]/download | API key + dataset access token | Filtered detokenized export |
| POST | /datasets/[id]/access-token | Session | Issue short-lived dsat_ token |
| POST | /datasets/[id]/public-share | Session | One-time public link |
Upload details: Datasets Upload.
Default limits
| Variable | Default |
|---|---|
VEILIO_DATASET_MAX_BYTES | 320 MB (335 544 320 bytes) |
VEILIO_DATASET_MAX_CELLS | 200 000 cells |
Common errors
| HTTP | Code | Meaning |
|---|---|---|
| 401 | AUTH_ERROR | Missing / invalid key or session |
| 400 | VALIDATION_ERROR | Bad payload |
| 403 | PLAN_LIMIT | Quota exceeded |
| 403 | FORBIDDEN | RBAC (e.g. VIEWER write) |
| 408 | TIMEOUT_ERROR | Request timeout |
| 410 | TOKEN_SHREDDED | Token cryptographically destroyed |
| 413 | PAYLOAD_TOO_LARGE | Dataset file too large |
| 429 | RATE_LIMIT_ERROR | Rate limit exceeded |
| 500 | INTERNAL_ERROR | Server error |
Full troubleshooting: Troubleshooting.
OpenAPI specification
A machine-readable OpenAPI 3.0 file is available in the Veilio documentation repository:
docs/gitbook/openapi.yaml
Import it into Postman, Insomnia, or your API gateway for interactive testing.
SDKs
Docs: SDK JS · SDK Python