Data Lifecycle: Retention and Crypto Shredding

Veilio supports lifecycle control for tokenized data through retention metadata and irreversible crypto shredding.

Important: setting retention at tokenize time only schedules destruction. Tokens are shredded automatically only if a job calls /api/internal/tokens/auto-shred on a schedule. Without that job, expired tokens remain detokenizable.

Retention at tokenization time

When tokenizing data, you can define retention via:

Field	Type	Description
`ttlDays`	positive int	Shred after N days from tokenization
`retentionUntil`	ISO datetime	Absolute shred date (e.g. `2027-01-01T0000.000Z`)

Provide one of the two. Example:

bash

curl -s -X POST "$VEILIO_BASE_URL/tokenize" \
  -H "Authorization: Bearer $VEILIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "john@example.com",
    "type": "email",
    "retention": { "ttlDays": 90 }
  }'

Response includes the resolved date:

json

{
  "token": "tok_abc123...",
  "createdAt": "2026-07-26T0800.000Z",
  "retentionUntil": "2026-10-24T0800.000Z"
}

The same retention object works with /tokenize/bulk, /tokenize/format, and the JS/Python SDKs.

Auto-shredding (required for TTL / retentionUntil)

Internal route processes expired tokens in batches:


Endpoint	`POST /api/internal/tokens/auto-shred`
Auth	`Authorization: Bearer $VEILIO_CRON_SECRET`
Query	`limit` (optional, default `500`, max `5000`)

What it does: finds tokens where retentionUntil <= now and shreddedAt is null, then crypto-shreds them (encrypted payload cleared, detokenization returns 410 TOKEN_SHREDDED).

Configure the secret

In your environment (required on on-premise; already set on Veilio SaaS):

bash

VEILIO_CRON_SECRET=$(openssl rand -base64 32)

Schedule the job

Recommended: hourly. Example crontab on the host:

bash

0 * * * * curl -fsS -X POST "https://your-domain.com/api/internal/tokens/auto-shred?limit=500" \
  -H "Authorization: Bearer $VEILIO_CRON_SECRET" \
  >> /var/log/veilio-auto-shred.log 2>&1

One-shot test:

bash

curl -s -X POST "https://your-domain.com/api/internal/tokens/auto-shred?limit=500" \
  -H "Authorization: Bearer $VEILIO_CRON_SECRET"

Success response:

json

{
  "processed": 12,
  "limit": 500,
  "executedAt": "2026-07-26T0901.000Z"
}

If more than limit tokens expire at once, the next cron run continues the backlog.

Environment	Who runs the cron?
SaaS (`app.veilio.fr`)	Veilio — you only pass `retention` when tokenizing
On-premise	You — set `VEILIO_CRON_SECRET` and schedule the job

See also: Installation guide (on-premise env + ops checklist).

On-demand shredding

Use POST /api/tokens/shred to shred a token immediately with an API key (GDPR erasure, early deletion, etc.).

bash

curl -X POST "https://app.veilio.fr/api/tokens/shred" \
  -H "Authorization: Bearer $VEILIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "tok_xxxxxxxxxxxx", "reason": "GDPR - user deletion request"}'

On-premise: replace the host with your instance URL (https://your-domain.com/api/tokens/shred).

Do not use DELETE /api/tokens/[id] — that route is dashboard-only (browser session required) and will always return 401 when called with an API key.

Request body

Field	Type	Required	Description
`token`	string	Yes	The `tok_...` value returned at tokenization time
`reason`	string	No	Audit log label (max 500 chars)

Success (200)

json

{
  "token": "tok_xxxxxxxxxxxx",
  "shreddedAt": "2026-05-06T1600.000Z"
}

Error codes

HTTP	Code	Cause
401	`AUTH_ERROR`	Missing, invalid, or revoked API key
404	`NOT_FOUND`	Token not found
403	`FORBIDDEN`	Token belongs to a different organization
400	`VALIDATION_ERROR`	Missing `token` field or invalid body shape

SDK equivalents: client.shredToken({ token, reason }) (JS) / client.shred_token(token, reason=...) (Python).

Detokenization behavior after shredding

Once shredded, detokenization returns:

HTTP status: 410
code: TOKEN_SHREDDED

The operation is irreversible: encrypted data and search index are cleared.

Operational guidance

Use retention defaults for sensitive classes (email / phone / ID).
Keep shred reason values meaningful for auditability.
On-premise: treat auto-shred as a production go-live requirement if you use ttlDays / retentionUntil.
Monitor cron logs (processed count) so a silent auth failure (401) does not leave expired data live.
Prefer hourly (or more frequent) runs for predictable compliance; increase limit if you ingest large batches with short TTLs.

Data Lifecycle: Retention and Crypto Shredding

Veilio supports lifecycle control for tokenized data through retention metadata and irreversible crypto shredding.

Important: setting retention at tokenize time only schedules destruction. Tokens are shredded automatically only if a job calls /api/internal/tokens/auto-shred on a schedule. Without that job, expired tokens remain detokenizable.

Retention at tokenization time

When tokenizing data, you can define retention via:

Field	Type	Description
`ttlDays`	positive int	Shred after N days from tokenization
`retentionUntil`	ISO datetime	Absolute shred date (e.g. `2027-01-01T0000.000Z`)

Provide one of the two. Example:

bash

curl -s -X POST "$VEILIO_BASE_URL/tokenize" \
  -H "Authorization: Bearer $VEILIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "john@example.com",
    "type": "email",
    "retention": { "ttlDays": 90 }
  }'

Response includes the resolved date:

json

{
  "token": "tok_abc123...",
  "createdAt": "2026-07-26T0800.000Z",
  "retentionUntil": "2026-10-24T0800.000Z"
}

The same retention object works with /tokenize/bulk, /tokenize/format, and the JS/Python SDKs.

Auto-shredding (required for TTL / retentionUntil)

Internal route processes expired tokens in batches:


Endpoint	`POST /api/internal/tokens/auto-shred`
Auth	`Authorization: Bearer $VEILIO_CRON_SECRET`
Query	`limit` (optional, default `500`, max `5000`)

What it does: finds tokens where retentionUntil <= now and shreddedAt is null, then crypto-shreds them (encrypted payload cleared, detokenization returns 410 TOKEN_SHREDDED).

Configure the secret

In your environment (required on on-premise; already set on Veilio SaaS):

bash

VEILIO_CRON_SECRET=$(openssl rand -base64 32)

Schedule the job

Recommended: hourly. Example crontab on the host:

bash

0 * * * * curl -fsS -X POST "https://your-domain.com/api/internal/tokens/auto-shred?limit=500" \
  -H "Authorization: Bearer $VEILIO_CRON_SECRET" \
  >> /var/log/veilio-auto-shred.log 2>&1

One-shot test:

bash

curl -s -X POST "https://your-domain.com/api/internal/tokens/auto-shred?limit=500" \
  -H "Authorization: Bearer $VEILIO_CRON_SECRET"

Success response:

json

{
  "processed": 12,
  "limit": 500,
  "executedAt": "2026-07-26T0901.000Z"
}

If more than limit tokens expire at once, the next cron run continues the backlog.

Environment	Who runs the cron?
SaaS (`app.veilio.fr`)	Veilio — you only pass `retention` when tokenizing
On-premise	You — set `VEILIO_CRON_SECRET` and schedule the job

See also: Installation guide (on-premise env + ops checklist).

On-demand shredding

Use POST /api/tokens/shred to shred a token immediately with an API key (GDPR erasure, early deletion, etc.).

bash

curl -X POST "https://app.veilio.fr/api/tokens/shred" \
  -H "Authorization: Bearer $VEILIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "tok_xxxxxxxxxxxx", "reason": "GDPR - user deletion request"}'

On-premise: replace the host with your instance URL (https://your-domain.com/api/tokens/shred).

Do not use DELETE /api/tokens/[id] — that route is dashboard-only (browser session required) and will always return 401 when called with an API key.

Request body

Field	Type	Required	Description
`token`	string	Yes	The `tok_...` value returned at tokenization time
`reason`	string	No	Audit log label (max 500 chars)

Success (200)

json

{
  "token": "tok_xxxxxxxxxxxx",
  "shreddedAt": "2026-05-06T1600.000Z"
}

Error codes

HTTP	Code	Cause
401	`AUTH_ERROR`	Missing, invalid, or revoked API key
404	`NOT_FOUND`	Token not found
403	`FORBIDDEN`	Token belongs to a different organization
400	`VALIDATION_ERROR`	Missing `token` field or invalid body shape

SDK equivalents: client.shredToken({ token, reason }) (JS) / client.shred_token(token, reason=...) (Python).

Detokenization behavior after shredding

Once shredded, detokenization returns:

HTTP status: 410
code: TOKEN_SHREDDED

The operation is irreversible: encrypted data and search index are cleared.

Operational guidance

Use retention defaults for sensitive classes (email / phone / ID).
Keep shred reason values meaningful for auditability.
On-premise: treat auto-shred as a production go-live requirement if you use ttlDays / retentionUntil.
Monitor cron logs (processed count) so a silent auth failure (401) does not leave expired data live.
Prefer hourly (or more frequent) runs for predictable compliance; increase limit if you ingest large batches with short TTLs.

Data Lifecycle: Retention and Crypto Shredding

Retention at tokenization time

Auto-shredding (required for TTL / retentionUntil)

On-demand shredding

Detokenization behavior after shredding

Operational guidance

Related links

Data Lifecycle: Retention and Crypto Shredding

Retention at tokenization time

Auto-shredding (required for TTL / retentionUntil)

On-demand shredding

Detokenization behavior after shredding

Operational guidance

Related links