Skip to main content
ALTCHA®

Privacy & data handling

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.

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:

CookieSet byWhenPurpose
jwtSentinelAn 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_stateSentinelAn 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_cookieYour applicationOnly when you configure seed_cookie and your application sets it.Optional per-user seed of the 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.

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

See [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.

PartDerived 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.

DataPersonal data in itKept forControlled by
Request logs (main database)Client IP, country, browser and device labels, network type, referrer72h 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 above90d by default (1 day to 5 years)[clickhouse] raw_retention
Hourly request statsNo IP; counts per country, browser, device, network, referrer, error, and ruleForever in the main database; 5 years in ClickHouse—
Audit logsAdmin username and user ID, client IP, user agent90d by default (1 to 3650 days)[audit_logs] retention, enabled
AlertsClient IPs and usernames in the subject, message, and details90d after last raised (1 to 3650 days)[alerts] retention, enabled
Threat entriesFull IP or CIDRAuto 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 key30m after the last increase[penalty] ttl
Rate-limit counters (KV)Full client IP or EDK in the keyThe limit's window[rate_limit] global, security-group rate limits
Threat signal counters (KV)Full client IP in the keyThe signal's window (5m by default)[threats.signals]
Campaign counters (KV)Client IP markers per message fingerprintThe campaign window, 1h by default[similarity.campaign] window, enabled
Training suggestionsSubmitted message text7d by default (1 hour to 90 days); off by default[similarity.suggestions] enabled, retention
Training dataWhatever text you or your backend add as samplesUntil deletedAdmin UI or API
SnapshotsCopies of the tables above, including request logs, audit logs, and alertsScheduled: 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:

[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:

{
  "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::.

WhereAnonymized
Request logsYes
Audit logsYes
Alerts and their webhook, email, and push deliveriesYes, unless [alerts] anonymize_ip overrides it
Server log linesYes
Threat entriesNo: an entry must hold the address it blocks
Rate limits, penalties, geolocation, threat lookups, security-group rulesNo: they use the full IP while handling the request
Admin AI assistantNo: 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.

IntegrationData sentWhenHow to disable
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 = trueOff by default; [classifier.ai] provider = "none"; narrow classifier.aiSignals
OpenAI embeddings (or another OpenAI-compatible API)Classified texts in up to max_chunks chunks, and your training samplesEach classification that uses training data, and each new sampleOff by default; [similarity] provider = "none" or "local"
IP resolver APIs (ip-api.com, ipstack, ipinfo)The full client IP, plus your API keyEach 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 IPOnly when an admin uses AI Assistant in the admin UI[assistant] enabled = false
License server (license.altcha.org)The license key, the deployment ID, the Sentinel version, the number of instances in use, and a hash of the current licenseActivation and about once a day, only with [license] keyUse a license file instead of a key
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 scheduleDisable each list, point it at your own mirror, or use local paths; see Air-gapped deployments
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_ipWhen an alert is raisedRemove [[alerts.webhooks]], [alerts.email], push subscriptions

The keys and defaults are in the configuration reference: [classifier.ai], [similarity.openai], [[ip_resolver.providers]], [assistant], [license], and [releases].

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.

DataHow to delete it
Request logs, audit logs, alertsNo delete endpoint; they expire with their retention. Shorten [request_logs] retention, [audit_logs] retention, or [alerts] retention if needed.
Threat entriesDELETE /v2/threat-entries/{id} (root) or the admin UI; find the entry with POST /v2/threat-entries/_search. See the threat-entries API.
Training dataDELETE /v2/training-data/{id}; search with POST /v2/training-data/_search.
Training suggestionsDELETE /v2/training-suggestions/{id}; search with POST /v2/training-suggestions/_search.
Admin usersDelete 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.
SnapshotsDelete old snapshot files from your storage.

To answer an access request, search the stores that hold IPs: POST /v2/request-logs/_search with an ip filter, POST /v2/audit-logs/_search, and POST /v2/alerts/_search. With anonymization on, search for the truncated IP.

Start typing to search...

↑ ↓ Navigate ↵ Select