# Privacy & data handling

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

This page describes the personal data Sentinel processes, where it stores it and for how long, and what leaves your infrastructure. Use it for your records of processing, your privacy notice, and to decide which options to turn off.

Sentinel is self-hosted: everything it stores stays in your database, KV store, and object storage. Data goes to a third party only through the optional integrations listed in [Third-party integrations](#third-party-integrations).

## Cookies

Sentinel sets no cookies on your visitors. The widget endpoints (`GET /v2/challenge`, `POST /v2/verify`) never send `Set-Cookie`, and challenges carry everything they need in their payload.

Two cookies exist, and neither involves visitors by default:

| Cookie | Set by | When | Purpose |
| --- | --- | --- | --- |
| `jwt` | Sentinel | An admin signs in to the admin UI or API (password, LDAP, passkey, or SSO). | Admin session. `HttpOnly; Secure; SameSite=Strict; Path=/`, expires after `[auth] jwt_ttl` (`24h` by default). Signing out clears it. |
| `oauth_state` | Sentinel | An admin starts an SSO sign-in. | Encrypted state of that sign-in. `HttpOnly; Secure; SameSite=Lax`, expires after 10 minutes and is cleared at the callback. |
| Name of `[edk] seed_cookie` | **Your application** | Only when you configure `seed_cookie` and your application sets it. | Optional per-user seed of the [EDK](#ephemeral-device-key-edk). Sentinel only reads it. |

The seed cookie is opt-in. When you set `[edk] seed_cookie` (for example `"edk_seed"`), Sentinel reads that cookie from widget requests and, if its value is `<seed>.<hex HMAC-SHA256(seed_cookie_secret, seed)>` with a valid signature, mixes the seed into the device part of the EDK. Sentinel never creates or changes this cookie. Your application decides whether to set it, what the seed is (for example a user ID), and how long it lives, so the consent question for that cookie is yours. A cookie with a missing or wrong signature is ignored. Browsers only send it to Sentinel when Sentinel is on the same site as your application.

```toml
[edk]
seed_cookie        = "edk_seed"
seed_cookie_secret = "${EDK_SEED_COOKIE_SECRET}"   # at least 24 characters
```

See [`[edk]`](/docs/sentinel/v2/reference/configuration/#edk) for the keys and `seed_header`, the proxy-set alternative.

## Ephemeral Device Key (EDK)

The EDK is a 32-character hex identifier that lets Sentinel recognize "the same device, today" for rate limits and challenge binding, without a cookie and without a persistent ID. It is computed per request; it isn't a stored profile.

| Part | Derived from |
| --- | --- |
| Network (first 16 hex characters) | The day and the client IP (an IPv6 address reduced to its `/64`) |
| Device (last 16 hex characters) | The day, the client IP, `User-Agent` (else `sec-ch-ua`), `Accept-Language`, and the optional seed from `[edk] seed_header` or `seed_cookie` |

Both parts are HMAC-SHA256 values, truncated to 8 bytes, under a key derived from `[secrets] encryption_key`. Without that key, an EDK can't be recomputed or reversed to the IP or headers.

What it can and can't do:

- **It changes every day.** The day is part of the input, so the same device gets an unrelated EDK after midnight in `[edk] time_zone` (UTC by default). EDKs of different days can't be linked.
- **It lives at most two days in practice.** `POST /v2/verify` also accepts yesterday's EDK, so a challenge solved across midnight still verifies. Rate-limit and other KV keys built on it expire with their window.
- **It groups requests, not people.** Devices with the same IP, browser string, and languages share an EDK; one device changes its EDK when its IP or browser changes. Only a seed you supply (a user ID, for example) ties it to a person.
- **It isn't stored in request logs, audit logs, or alerts.** It appears in the challenge payload sent to the browser, in `GET /v2/inspect`, and in KV keys of security-group rate limits keyed by `edk`.

## Data Sentinel stores

The table lists every store that can hold personal data, how long it's kept, and the key that controls it. "Personal data" here means IP addresses, user agents, usernames, and submitted text.

| Data | Personal data in it | Kept for | Controlled by |
| --- | --- | --- | --- |
| [Request logs](/docs/sentinel/v2/operations/request-logs/) (main database) | Client IP, country, browser and device labels, network type, referrer | `72h` by default (at least `2h`) | `[request_logs] retention`; logging is off unless the API key's `requestLogging` is `verification` or `all` |
| Request logs (ClickHouse) | As above | `90d` by default (1 day to 5 years) | `[clickhouse] raw_retention` |
| Hourly request stats | No IP; counts per country, browser, device, network, referrer, error, and rule | Forever in the main database; 5 years in ClickHouse | — |
| [Audit logs](/docs/sentinel/v2/operations/audit-logs/) | Admin username and user ID, client IP, user agent | `90d` by default (1 to 3650 days) | `[audit_logs] retention`, `enabled` |
| [Alerts](/docs/sentinel/v2/operations/alerts/) | Client IPs and usernames in the subject, message, and details | `90d` after last raised (1 to 3650 days) | `[alerts] retention`, `enabled` |
| [Threat entries](/docs/sentinel/v2/features/threat-intelligence/) | Full IP or CIDR | Auto entries: `48h` by default; manual entries: until their `expiresAt`, or forever | `[threats.signals]` `expire`; the entry's `expiresAt` |
| Penalty scores (KV) | Account ID + full client IP in the key | `30m` after the last increase | `[penalty] ttl` |
| Rate-limit counters (KV) | Full client IP or EDK in the key | The limit's window | `[rate_limit] global`, security-group rate limits |
| Threat signal counters (KV) | Full client IP in the key | The signal's window (`5m` by default) | `[threats.signals]` |
| Campaign counters (KV) | Client IP markers per message fingerprint | The campaign window, `1h` by default | `[similarity.campaign] window`, `enabled` |
| [Training suggestions](/docs/sentinel/v2/features/similarity/) | Submitted message text | `7d` by default (1 hour to 90 days); off by default | `[similarity.suggestions] enabled`, `retention` |
| Training data | Whatever text you or your backend add as samples | Until deleted | Admin UI or API |
| [Snapshots](/docs/sentinel/v2/operations/snapshots/) | Copies of the tables above, including request logs, audit logs, and alerts | Scheduled: newest `7` kept; manual: until you delete them | `[snapshots] keep`, `exclude_tables` |

Sentinel doesn't store the form fields it classifies or the challenge solutions it verifies. Submitted content reaches storage only through training suggestions, training data, and the attachments of `POST /v2/eml` requests that ask for an upload to `[storage]` with `X-Attachments-Upload`.

Retention runs in the background: expired audit logs and alerts are deleted hourly, raw request logs once they pass their retention (after their hour has been folded into the hourly stats), and expired threat entries at each `[threats] sync_interval`. Snapshots taken before a deletion still hold the old rows; use `[snapshots] exclude_tables` (for example `["request_logs", "audit_logs", "alerts"]`) if they shouldn't.

## IP anonymization

`[privacy] anonymize_ip` is off by default. Turn it on to store client IPs truncated:

```toml
[privacy]
anonymize_ip = true
```

It zeroes the last IPv4 octet or the last IPv6 segment of public IPs before they're stored or printed. Private, loopback, link-local, and unspecified addresses are kept as is. An audit-log entry for a failed sign-in from `203.0.113.77`:

```json
{
"action": "auth.login",
"outcome": "failure",
"code": "INVALID_CREDENTIALS",
"username": "root",
"ip": "203.0.113.0",
"userAgent": "curl/8.7.1",
…
}
```

`2001:db8:abcd:12::77` is stored as `2001:db8:abcd:12::`.

| Where | Anonymized |
| --- | --- |
| Request logs | Yes |
| Audit logs | Yes |
| Alerts and their webhook, email, and push deliveries | Yes, unless `[alerts] anonymize_ip` overrides it |
| Server log lines | Yes |
| Threat entries | No: an entry must hold the address it blocks |
| Rate limits, penalties, geolocation, threat lookups, security-group rules | No: they use the full IP while handling the request |
| Admin AI assistant | No: see below |

Anonymization applies when the data is written. Turning it on doesn't rewrite IPs already stored; they expire with their retention. The request-log filter on `ip` matches the stored value, so search for `203.0.113.0` once anonymization is on.

## Third-party integrations

Every integration that sends data off your infrastructure is optional. The ones on by default send no visitor data.

| Integration | Data sent | When | How to disable |
| --- | --- | --- | --- |
| [AI decider](/docs/sentinel/v2/features/ai-decider/) (TypeSafe, or OpenRouter and TypeSafe) | The first `max_chars` (`4000`) characters of the text, the group's `classifier.aiPurpose` and `aiInstructions`, and the enabled signals: country, network provider and type, browser and OS, languages, time zone; optionally threat kinds and the email domain. Never the IP, the full email address, field names, or IDs. | Each classification in a security group with `classifier.ai = true` | Off by default; `[classifier.ai] provider = "none"`; narrow `classifier.aiSignals` |
| [OpenAI embeddings](/docs/sentinel/v2/features/similarity/) (or another OpenAI-compatible API) | Classified texts in up to `max_chunks` chunks, and your training samples | Each classification that uses training data, and each new sample | Off by default; `[similarity] provider = "none"` or `"local"` |
| [IP resolver APIs](/docs/sentinel/v2/configure/ip-resolvers/) (ip-api.com, ipstack, ipinfo) | The full client IP, plus your API key | Each lookup not in the cache: logged requests, `POST /v2/ip`, IP classification, root sign-ins with `[alerts.root_login_country]` | Off by default; remove the provider, or use a local `.mmdb` database. The free ip-api.com and ipstack endpoints use plain HTTP. |
| Admin AI assistant (altcha-ai at `eu.altcha.org`) | The admin's question, chat history, the account ID, the admin UI section and language, the configuration shown on screen (never secrets), the admin's role and permissions, the Sentinel version, and the admin's full client IP | Only when an admin uses **AI Assistant** in the admin UI | `[assistant] enabled = false` |
| [License server](/docs/sentinel/v2/configure/licensing/) (`license.altcha.org`) | The license key, the deployment ID, the Sentinel version, the number of instances in use, and a hash of the current license | Activation and about once a day, only with `[license] key` | Use a license file instead of a key |
| [Remote files](/docs/sentinel/v2/configure/remote-files/) (`directory.altcha.org`, MaxMind, Hugging Face, threat-list hosts) | A download request with `User-Agent: altcha-sentinel/<version>` and your provider credentials. No visitor data. | On each file's schedule | Disable each list, point it at your own mirror, or use local paths; see [Air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/) |
| Release feed (`altcha.org`) | A `GET` with `User-Agent: altcha-sentinel/<version>`. No visitor data. | Every `6h` by default | `[releases] enabled = false` |
| Alert deliveries (your webhooks, SMTP server, browser push services) | Alert content: subjects, messages, and details, with IPs anonymized under `[alerts] anonymize_ip` | When an alert is raised | Remove `[[alerts.webhooks]]`, `[alerts.email]`, push subscriptions |

<Callout type="warning" title="The assistant sends the admin's full IP">

`[privacy] anonymize_ip` doesn't apply to the admin AI assistant: it forwards the signed-in admin's client IP as is. It's on by default; set `[assistant] enabled = false` if admins must not send data to ALTCHA.

The keys and defaults are in the [configuration reference](/docs/sentinel/v2/reference/configuration/): [`[classifier.ai]`](/docs/sentinel/v2/reference/configuration/#classifierai), [`[similarity.openai]`](/docs/sentinel/v2/reference/configuration/#similarityopenai), [`[[ip_resolver.providers]]`](/docs/sentinel/v2/reference/configuration/#ip_resolverproviders), [`[assistant]`](/docs/sentinel/v2/reference/configuration/#assistant), [`[license]`](/docs/sentinel/v2/reference/configuration/#license), and [`[releases]`](/docs/sentinel/v2/reference/configuration/#releases).

## GDPR and legal basis

Sentinel is built for data minimization, so you can usually rely on **legitimate interest** (GDPR Art. 6(1)(f)): protecting your forms and APIs from abuse, with processing limited to what that needs.

- **No consent banner for Sentinel itself.** Sentinel sets no visitor cookies and stores nothing on the device. If you enable `[edk] seed_cookie`, assess the cookie your application sets.
- **Short-lived identifiers.** The EDK changes daily and can't be linked across days or reversed without your encryption key.
- **Minimal storage by default.** Request logging is off per API key until you turn it on, raw logs expire after `72h`, and `[privacy] anonymize_ip` truncates stored IPs.
- **Processors.** Sentinel runs on your infrastructure, so ALTCHA doesn't process your visitors' data. The AI decider, OpenAI embeddings, and IP lookup APIs are third-party processors if you enable them; list them in your records and check their terms.

## Data subject requests

Sentinel stores no account for visitors, so a request usually concerns an IP address, an admin account, or submitted text.

| Data | How to delete it |
| --- | --- |
| Request logs, audit logs, alerts | No delete endpoint; they expire with their retention. Shorten `[request_logs] retention`, `[audit_logs] retention`, or `[alerts] retention` if needed. |
| Threat entries | `DELETE /v2/threat-entries/{id}` (root) or the admin UI; find the entry with `POST /v2/threat-entries/_search`. See the [threat-entries API](/sentinel-api-docs-v2.html#tag/threat-entries). |
| Training data | `DELETE /v2/training-data/{id}`; search with [`POST /v2/training-data/_search`](/sentinel-api-docs-v2.html#tag/training-data/POST/v2/training-data/_search). |
| Training suggestions | `DELETE /v2/training-suggestions/{id}`; search with [`POST /v2/training-suggestions/_search`](/sentinel-api-docs-v2.html#tag/training-suggestions/POST/v2/training-suggestions/_search). |
| Admin users | Delete the user in the admin UI or with the users API; their audit-log entries expire with `[audit_logs] retention`. |
| KV entries (penalties, rate limits, signals, campaigns) | Expire on their own within minutes to hours. |
| Snapshots | Delete old snapshot files from your storage. |

To answer an access request, search the stores that hold IPs: [`POST /v2/request-logs/_search`](/sentinel-api-docs-v2.html#tag/request-logs/POST/v2/request-logs/_search) with an `ip` filter, [`POST /v2/audit-logs/_search`](/sentinel-api-docs-v2.html#tag/audit-logs/POST/v2/audit-logs/_search), and [`POST /v2/alerts/_search`](/sentinel-api-docs-v2.html#tag/alerts/POST/v2/alerts/_search). With anonymization on, search for the truncated IP.

## Related

- [Production checklist](/docs/sentinel/v2/security/production-checklist/)
- [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/)
- [Request logs](/docs/sentinel/v2/operations/request-logs/)
- [Audit logs](/docs/sentinel/v2/operations/audit-logs/)
- [Rate limiting](/docs/sentinel/v2/features/rate-limiting/)
- [Outbound proxy & air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/)
- [Configuration reference: `[privacy]`](/docs/sentinel/v2/reference/configuration/#privacy)
