Dataset Access Tokens

Dataset Access Tokens are short-lived signed tokens designed for controlled dataset sharing. They are scoped and safer than long-lived static credentials for one-off dataset access from terminal scrip

Why this exists

• Limit token lifetime by default
• Scope access to one dataset
• Preserve role-based column filtering
• Reduce risk if a token leaks

How it works

1. Owner or DPO generates/rotates a dataset share key from the dashboard.
2. Veilio returns a short-lived Dataset Access Token.
3. Consumer calls dataset download endpoint with the token header.
4. Veilio enforces:

   • token signature validity
   • expiration (exp)
   • dataset scope
   • organization scope
   • role-based column policies

Header and token format

• Header: x-veilio-dataset-access-token
• Token prefix: dsat_...

TTL defaults and limits

• Default TTL: 15 minutes
• Configurable presets (dashboard): 15m, 1h, 8h, 24h, 7d
• Max TTL (server side): 24h in the current token utility (unless overridden in code/policy)

Example (curl)

curl -sSf \
  -H "x-veilio-dataset-access-token: dsat_xxx.yyy" \
  "https://app.veilio.xyz/api/datasets/<DATASET_ID>/download" \
  -o export.csv

Security notes

• Use HTTPS only.
• Never store tokens in source control.
• Prefer short TTL for ad-hoc/manual use.
• Rotate tokens after partner offboarding or scope change.

Personal datasets (no organization required)

Freemium, Starter, and Pro plans can upload datasets without being part of an organization. Column policies and org-wide sharing (share key, member access) still require an organization.

Secure one-time download links

Share a dataset with someone who has no Veilio account via a single-use signed URL.

Create a share link

curl -X POST "https://app.veilio.xyz/api/datasets/{DATASET_ID}/public-share" \
  -H "Cookie: <session>" \
  -H "Content-Type: application/json" \
  -d '{
    "columnsToExpose": ["email", "first_name"],
    "ttlPreset": "24h",
    "recipientEmail": "[e-mail]"
  }'

Field	Type	Required	Description
columnsToExpose	string[]	✅	Columns to deliver in plaintext. Other columns are omitted.
ttlPreset	string	✅	15m · 1h · 8h · 24h · 7d
recipientEmail	string	❌	If provided, an email with the link is sent automatically.

Response

{
"shareUrl": "https://app.veilio.xyz/api/datasets/{id}/download?public_token=...",
"expiresAt": "2026-05-07T16:00:00.000Z"
}

The recipient opens the link in any browser or curl — no Veilio account needed. The link is single-use: it is permanently revoked after the first download. After expiry or first use, the endpoint returns 410 Gone.

---

Dataset access token revocation

Starting from token format v4, rotating the share key from the dashboard immediately invalidates all dsat_ tokens previously issued with the old key — no need to wait for their natural expiry.

This means: if a partner is offboarded or a key is compromised, regenerating the share key is sufficient to cut off access instantly.