Developer Platform API

---

Quick reference

Base URL

Environment	URL
Production (SaaS)	https://app.veilio.xyz/api
On-premise	https://<your-domain>/api
Local / dev	http://localhost:3000/api

Use https://app.veilio.xyz/api, not api.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)

Plan	Tokens / month	Requests / month	API keys	Datasets	Members	Bulk	Multi-format
Freemium	500	1 000	1	1	1	No	No
Starter	2 000	10 000	2	4	1	Yes	Yes
Pro	10 000	100 000	5	10	2	Yes	Yes
Enterprise	Custom	Custom	Custom	Unlimited	Unlimited	Yes	Yes

A request counts successful TOKENIZE, DETOKENIZE, SHRED, and DATASET_UPLOAD operations. 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": "[e-mail]",
  "type": "email",
  "metadata": { "entityId": "customer_42" },
  "retention": { "ttlDays": 365 }
}

// Response 200
{
  "token": "tok_...",
  "createdAt": "2026-03-26T10:00:00.000Z",
  "retentionUntil": "2027-03-26T10:00:00.000Z"
}

POST /tokenize/bulk

// Request
{
  "fields": [
    { "data": "[e-mail]", "type": "email" },
    { "data": "+336...", "type": "phone", "retention": { "ttlDays": 30 } }
  ]
}

// Response 200
{
  "tokens": [{ "token": "tok_...", "type": "email", "createdAt": "...", "retentionUntil": null }],
  "summary": { "total": 2, "success": 2, "failed": 0 },
  "errors": [{ "field": 1, "error": "..." }],
  "createdAt": "..."
}

POST /flows/ingest

// Request
{
  "flowId": "signup-v1",
  "source": "website",
  "entityId": "lead_42",
  "data": { "email": "[e-mail]", "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)
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 by ids[] or entityId
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

Note: POST /tokens/lookup is not available with an API key. For backend integrations, store entityId in token metadata at tokenization time and query your own database by token ID.

---

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

Language	Package
JavaScript / TypeScript	@veilio/sdk on npm
Python	veilio-sdk on PyPI

Docs: SDK JS · SDK Python