> For the complete documentation index, see [llms.txt](https://docs.veilio.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veilio.xyz/documentation/basics/datasets.md).

# 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)

```bash
curl -sSf \
  -H "x-veilio-dataset-access-token: dsat_xxx.yyy" \
  "https://app.veilio.fr/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.&#x20;

#### **Create a share link**

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

| 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.fr/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.<br>