> 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

### 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.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.&#x20;

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

```bash
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": "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.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.<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veilio.xyz/documentation/basics/datasets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.