Breaking changes in v2
This page lists every v1 to v2 change that needs action, grouped by who it affects. Use it together with the upgrade checklist. Configuration changes are listed per variable in Config mapping; features that no longer exist are in Removed features.
| Audience | Read |
|---|---|
| Frontend developers | License, Widget & frontend |
| Backend developers | License, Backend integrations |
| Sentinel admins | Security groups, Admin sign-in, Management API & scripts |
| Operators | Operations, Data |
Two conventions apply to every /v2 endpoint except the widget endpoints and POST /v2/verify/signature: responses are wrapped in { "data": … }, and errors have the shape { "error", "statusCode", "code" }. Look up any code in Error codes.
License enforcement
Sentinel v2 doesn't run without a license, and v1's 30-day trial is gone.
- Without an active license, the functional API answers
403 LICENSE_NOT_ACTIVE:/v2/challenge,/v2/verify,/v2/inspect,/v2/classifier,/v2/similarity,/v2/ip,/v2/language,/v2/user-agent,/v2/time-zone,/v2/phishing,/v2/threat,/v2/threat/_report, and/v2/eml. Your widgets stop working. - An expired or refresh-overdue license keeps its features and limits, but it isn't active, so the functional API still stops.
- Without a usable license (none, revoked, or not yet valid), Sentinel also falls back to a baseline: embedded SQLite only, 3 instances, 1 account, 1 user, 1 API key, 1 security group, and no ClickHouse, audit logs, OAuth, or LDAP. Other database backends answer most
/v2routes with403 BACKEND_NOT_LICENSED, and extra replicas get503 LICENSE_INSTANCE_LIMIT. - Nothing is deleted. Over a limit, only creating more is refused (
403 LICENSE_LIMIT_REACHED). - The license is set in configuration only (
[license] keyorfile), followed by a restart. There is no admin UI or API to set it.
See Licensing and Plans & Licensing.
Widget & frontend
Widget v3 or later
Sentinel v2 serves only proof-of-work v2 challenges. Legacy SHA challenges and the X-Altcha-Config header are gone, so widgets up to 2.x don't work. Upgrade the widget to v3 or later before you switch traffic. In v3 the attribute is challenge:
<!-- v1 -->
<altcha-widget challengeurl="https://sentinel.example.com/v1/challenge?apiKey=key_…"></altcha-widget>
<!-- v2 -->
<altcha-widget challenge="https://sentinel.example.com/v2/challenge?apiKey=key_…"></altcha-widget>API key ids don't change in a migration, so only the path changes.
/v1 paths
The widget endpoints live under /v2. To keep /v1 URLs working during the transition, set [server] v1_compat = true. It serves these aliases on every listener, for widgets v3 or later only:
| v1 path | Served as |
|---|---|
GET /v1/challenge | GET /v2/challenge |
GET /v1/challenge/audio/{file} | GET /v2/challenge/audio/{file} |
POST /v1/verify | POST /v2/verify |
POST /v1/verify/signature | POST /v2/verify/signature, with v1's contract (see Verifying submissions) |
v1_compat is off by default, and no other /v1 path is served. Security-group rules still see the /v2 path. See Widget integration.
Widget keys must be public
GET/POST /v2/challenge, GET /v2/challenge/audio/{file}, and POST /v2/verify accept only keys of a public security group. A restricted or full key gets 403 BEARER_AUTH_PUBLIC_API_KEY when sent by id, or 403 PUBLIC_API_KEY_REQUIRED when sent with Basic. If a v1 widget used a key of a restricted or full group, move the key to a public group, or change the group's access to public. The migrate command prints a warning for every such group. See API keys & access levels.
Path prefix
v1's BASE_URL_PATH is the path of [server] base_url, for example https://example.com/sentinel. It prefixes the URLs handed to the widget: verifyUrl, the HIS url, and the code challenge audio. [server.public_api] and [server.admin_ui] have their own base_url.
Code challenge
- A wrong or missing
codeon/v2/verify(INCORRECT_CODE) burns the challenge; the widget fetches a new one. - A code solved less than
[code_challenge] min_solve_time(default4s) after issue, or before the spoken code ends once the audio was fetched, fails withTOO_FASTand burns the challenge. - The audio endpoint waits
[code_challenge] audio_delay(default3s), is limited per client IP byaudio_rate_limit(default10/5m), and answers only the network the challenge was issued to (the same IPv4 address or IPv6 /64); otherwise404 NOT_FOUND. - The image uses the
standardstyle by default: more noise, rotation, and vertical shift.codeChallenge.imageDifficulty = "low"restores the v1 look;"high"is harder. codeChallenge.audio = "false"turns the audio challenge off, andcodeChallenge.audioLanguageslimits it to the voices you list.- Code tokens are encrypted differently, so tokens issued by v1 don't decrypt in v2.
See Code challenge.
Human Interaction Signature
- With HIS on,
GET /v2/challengeanswers with a redirect and the widget posts its interaction data toPOST /v2/challenge. TheGETisn't counted against rule rate limits or logged; thePOSTis (v1 exempted both). - In
relaxedandstrictmode, a blocked visitor gets403 HIS_BLOCKED. - Replay detection now hashes the exact samples instead of statistics salted with the client IP. Sessions of one client no longer collide, a payload replayed from another IP is caught, and payloads with fewer than 8 sample intervals aren't tracked.
Settings and scores changed too; see Security groups and Data.
Backend integrations
Authentication
| Change | v1 | v2 |
|---|---|---|
restricted keys | Id alone accepted | Id and secret, Authorization: Basic base64("key_…:sec_…"), like full keys |
Only the id of a restricted/full key | 403 BEARER_AUTH_NO_FULL_API_KEY (full only) | 403 BEARER_AUTH_PUBLIC_API_KEY |
A public key with Basic | 403 BASIC_AUTH_FULL_API_KEY | 403 BASIC_AUTH_NON_PUBLIC_API_KEY |
| Detection endpoints with a session token | Accepted | Refused: 401 API_KEY_REQUIRED without a key, 403 NON_PUBLIC_API_KEY_REQUIRED with a public key |
accountId in the body | Selected the account | Ignored: the account is always the key's |
The detection endpoints that need a restricted or full key are /v2/ip, /v2/classifier, /v2/eml, /v2/language, /v2/phishing, /v2/threat, /v2/threat/_report, /v2/similarity, /v2/time-zone, /v2/user-agent, and /v2/training-data/_feedback. See the credential matrix.
curl -s https://sentinel.example.com/v2/classifier \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{"email": "jane@example.com", "text": "Hello"}'Endpoint map
| v1 | v2 | Notes |
|---|---|---|
POST /v1/classifier | POST /v2/classifier | See Classifier. |
POST /v1/eml | POST /v2/eml | See EML. |
POST /v1/ip | POST /v2/ip | networks (a list) replaces network; new errors lists failed resolver providers. |
POST /v1/language | POST /v2/language | See Language. |
POST /v1/phishing | POST /v2/phishing | See Phishing. |
POST /v1/similarity | POST /v2/similarity | Matches the account's training groups. |
POST /v1/threat | POST /v2/threat | |
POST /v1/threat/report | POST /v2/threat/_report | action is the IP's verdict after the report; use limitExceeded to tell whether this report listed the IP. |
POST /v1/timezone | POST /v2/time-zone | |
POST /v1/user-agent | POST /v2/user-agent | |
GET /v1/inspect | GET /v2/inspect | See Inspect. |
POST /v1/verify/signature | POST /v2/verify/signature | See Verifying submissions. |
Each /v2 response is wrapped in { "data": … }. Schemas are in the API reference.
Verifying submissions
POST /v2/verify/signature needs Basic authentication with a restricted or full key of the account that owns payload.apiKey, and that key's security group applies.
secretin the body is rejected with400 VALIDATION_ERROR.- A payload signed by another account's key returns
verified: falsewithreason: API_KEY_NOT_ALLOWED. verificationDatakeepsid,fieldsHash,device.edk, andparams.*as strings. v1 turned numeric-looking values, such as the zip code01234, into numbers.- The
/v1/verify/signaturealias (withv1_compat) needs no credentials and, like v1, answersWRONG_API_KEY_SECRETwhen a non-emptysecretisn't the payload key's.
Upgrade your server library to a version whose verifyServer supports v2, and pass a restricted key:
| Language | Library | Version |
|---|---|---|
| Node.js | altcha-lib | 2.9.0 |
| PHP | altcha-org/altcha | 2.4.0 |
| Python | altcha | 2.4.0 |
| Go | altcha-lib-go | 2.5.0 |
| .NET | Altcha | 1.2.0 |
import { verifyServer } from 'altcha-lib';
const result = await verifyServer({
payload: altcha, // the submitted `altcha` field
url: 'https://sentinel.example.com/v2/verify/signature',
apiKey: { id: 'key_…', secret: process.env.SENTINEL_API_KEY_SECRET! }, // restricted key
});Local verification with verifyServerSignature and the public key's secret keeps working, but read the renamed fields below. Examples for every library: Verifying submissions.
verificationData
| v1 field | v2 field | Notes |
|---|---|---|
challengeAlgorithm | challenge.algorithm | Also removed from the unsigned base64 payload JSON. |
hisScore | his.automation | The bot probability. his.score is now the sum of the HIS rules. |
hisAssistive | his.assistive | |
location.timeZone (undefined) | location.timeZone (empty) | Empty without a time zone. |
These keys keep their names: classification, expire, fields, fieldsHash, id, ipAddress, reasons, score, time, and verified.
New for verified solutions: challenge.issued, challenge.protectionLevel (frictionless or code_challenge), device.os, ip.asname, ip.countryCode, ip.networks, and with HIS, his.flags and his.mode. device.browser and device.type are signed again; device.type can take new values such as xr. With form fields, text.* and injection.* are signed too. See The verificationData fields.
Classifier
POST /v2/classifier returns the same categories, with these changes. Rule scores are in Classifier rules & scores.
- Device.
device.edkuses a new formula, so v1 and v2 EDKs never match. New rulesCLIandLIBRARYflag command-line clients and HTTP libraries. The ALTCHA native widgets (altcha-app,altcha-rn,altcha-flutter) are trusted apps and don't triggerUSER_AGENT_HEADER_UNCOMMON,CLI, orLIBRARY(security-group settingclassifier.trustedApps). The deviceBOTrule scores only a verified Web Bot Auth signature. - IP. New
ipruleBOTfor IPs on bot and crawler lists. The IP's threat score, which v1 added toip.score, is now theTHREAT_SCORErule: listed intriggeredRulesandreasons, and switchable withenableRules/disableRules.ipalso carries the/v2/ipfields (networks,threats,action,threatScore, …). - Location. Keeps its rules and fields.
timeZoneisnull(not omitted) when unknown, and the top-leveltimeZoneisnullrather than an object of nulls. The high-risk list is the security-group settingclassifier.highRiskCountries; there is no server-wide list. - Text. A built-in spam and profanity filter scores the body's
text(else the text offields), one rule per signal:SPAM_WORDS,PROFANITY,URL,LINK_MARKUP,CURRENCY,EXCLAMATION,REPEATED_CHARS,INVISIBLE_CHARS,MIXED_SCRIPT,RANDOM_CHARS,EMOJI,OBFUSCATION,CAPITALIZATION. Candidate languages come from the body'slanguages, else the detected language, else theAccept-Languageheader. - Phishing.
URL_PHISHINGlists URLs intext.phishing(url,phishId,target,submittedAt) instead ofrules.URL_PHISHING.tokens. It scores even withURLdisabled, matches URLs without a scheme and in markup, and raises the top-level score to at least2(BAD). - Injection. v1's text rules
SQL_INJECTIONandHTML_INJECTIONare now theinjectioncategory:SQL_INJECTION,HTML_INJECTION,EMAIL_HEADER_INJECTION,TEMPLATE_INJECTION, andNOSQL_INJECTION. They scan each field's key and value, the body'stextandemail, and list theirmatches. A triggered injection rule raises the top-level score to at least2(BAD). - Similarity. The
SIMILARITY:{group}rules and the body'ssimilarityarray are replaced by thesimilaritycategory:SIMILARITY(semantic match),NEAR_DUPLICATE, and the newCAMPAIGN. Semantic matching needs[similarity] provider(defaultnone). Groups come from the security-group settingclassifier.similarityGroupsor the body'ssimilarityGroups. A match whose best sample has weight 1 or more raises the score to at least2(BAD).
See Classifier.
Inspect
autopilotThreatis removed.penaltyis kept per account and client IP (v1: per EDK across all accounts), so rotating headers no longer resets it. Successful verifications don't add to it; new header hashes, rule rate-limit pressure, failed verifications (exceptCHALLENGE_EXPIRED), andpenalty.addrules do. It expires[penalty] ttl(default30m) after its last increase.riskisdevice.score+network.score+location.score, capped at 10 and rounded to one decimal, and the roottriggeredRuleslists what added to it. v1's ad-hoc terms are gone, the penalty no longer adds to it, and it applies to every key access level. It keeps no state.device.headerEntropyisnull(was0) without aheaderEntropy.limit. Past the limit,/v2/challengeand/v2/inspectanswer429 HEADER_ENTROPY.networkhas the/v2/ipfields plustimedOutand the network rules'rules,score, andtriggeredRules.networks(a list) replacesnetwork.device.headerHashis the first 8 bytes of SHA-256 (was xxh64), so v1 and v2 hashes differ.- The new
timeZonequery parameter enablesTIMEZONE_MISMATCH.
Language
- The detector covers 30 languages (v1: 50).
nocovers Bokmål and Nynorsk; Serbian, Croatian, and Bosnian are one language,sh. - There is no
enfallback. v1 answeredenwith probability0.35when the top probability was below 0.5; v2 returns the probabilities as detected, andlanguages: []for a text without letters. hintstake up to 50 language codes of up to 35 characters (de-AT,nb);texttakes up to 16000 characters.
Phishing
| v1 field | v2 field | Notes |
|---|---|---|
id | phishId | |
info | — | Removed (the PhishTank detail link). |
| — | url | The list URL that matched. |
submittedAt (Unix seconds, 0 when absent) | submittedAt (RFC 3339 or null) |
When the URL isn't listed, the entry fields are null, not omitted. The input url may be up to 2048 characters (v1: 500) and need not include a scheme. The default list is the ALTCHA directory's, not PhishTank's.
EML
X-Attachments-Uploadneeds a[storage]provider (s3orazure); without one the request is400 VALIDATION_ERROR. Local storage and/v1/blobsare removed.attachments[].contentUriis the native object URI (s3://bucket/keyor the Azure blob URL) plus?size=&type=&filename=; fetch it with your storage credentials. A failed upload is502 STORAGE_ERROR.- Without the upload header, attachments up to
X-Attachments-Size-Limitbytes (default5000000) are returned inline as base64content; larger ones havecontent: null. - Without
X-Authenticate, the trustedAuthentication-Resultsheader is the topmost one (the receiving server's), not the bottommost. - New fields:
authentication.DMARC,mail.links,triggeredRules, andattachments[].risks. - New rules include
DMARC_ALIGNMENT,LINK_TEXT_MISMATCH,SUSPICIOUS_LINK,LINK_PHISHING,MESSAGE_ID_ANOMALY,DATE_ANOMALY,BULK_MAILER,HTML_ONLY,HIDDEN_TEXT, andATTACHMENT_RISK. - The SPF client IP is the topmost
Receivedheader with a public IP. The classifier's IP rules use the sending server's IP (X-Smtp-Ip, else thatReceivedIP), falling back toX-Originating-IP. attachments[].checksumis SHA-256 (was MD5),inReplyTois a string (was an array), andheaders[].valueis always the raw unfolded value.- The body limit is
[eml] max_body_size(default5000000bytes); a larger body is413 PAYLOAD_TOO_LARGE.
See Email analysis (EML) and Classifier rules & scores.
Security groups
The migrate command translates v1 rules where it can. Use this section to review the result and to update anything that writes rules through the API.
Setting names
v2 rejects the old names.
v1 set field | v2 set field | Notes |
|---|---|---|
autopilot | — | Removed. Use the Recommended preset, or set rules conditioned on penalty, risk, or signal. |
powVersion | — | Removed; only proof-of-work v2 exists. |
algorithm, supportedAlgorithms | pow.algorithm | One algorithm. |
cost, counter, memoryCost, expires | pow.cost, pow.counter, pow.memoryCost, pow.expires | pow.expires takes a duration. |
rateLimit | rateLimit.limits | N/DURATION; the key goes in parentheses, e.g. 50/10m(key=edk). |
key | — | Part of rateLimit.limits: (key=edk), (key=ip), or (key=uid). |
rateLimitScope | rateLimit.scope | account or apiKey. |
classifyFields | classifier.fields | |
enableClassificationRules, disableClassificationRules | classifier.enableRules, classifier.disableRules | |
highRiskCountries | classifier.highRiskCountries | |
his | his.mode | off, monitor, relaxed, or strict; default off. |
hisBlockThreshold | his.blockThreshold | 0.1–1, default 0.8. |
hisHashTTL | his.hashTtl | 10m–7d, default 12h. |
| — | his.penalty | New: what relaxed and strict add to the penalty (default 1). |
headerEntropyLimit | headerEntropy.limit | N/DURATION, N 1–99, DURATION 1m–24h. |
headerEntropyRiskFactor | headerEntropy.penalty | Now added to the penalty for each new header hash beyond the first, instead of weighting risk. |
codeChallenge (true) | codeChallenge.enabled | true or false, default false. |
codeChallenge (adaptive) | — | Removed. Put a condition on the rule instead, e.g. penalty >= 3. |
codeChallengeAlphabet | codeChallenge.alphabet | 2–36 ASCII letters or digits, default 234579. |
codeChallengeMinLength, codeChallengeMaxLength | codeChallenge.length | N or MIN-MAX within 4–8, default 5. |
penalty | penalty.add | −10 to 10, one decimal; applied only when the rules allow the request. |
threats | — | Removed. Add a deny rule on threatVerdict = block. |
ai | — | Removed with AI security rules. Use the AI decider: classifier.ai, classifier.aiPurpose, classifier.aiInstructions. |
The full list of v2 settings is in the Rules reference.
Conditions
| v1 condition | v2 condition |
|---|---|
hosting, proxy, tor, mobile = true | network = hosting, proxy, tor, or mobile |
malicious = true, bot = true | signal = MALICIOUS, BOT |
country = list:high_risk | country = high_risk |
penalty with a range such as 4-10 | Two comparisons joined with and; each operator takes exactly one number from 0 to 10 |
ip with * | CIDR ranges; ip has no wildcards |
Comparison operators (>, >=, <, <=) are valid only on penalty and risk. See Rules reference.
Threat actions
The penalize action of threat sources and entries is removed (400 VALIDATION_ERROR). v1 added a penalized match's threatScore to the client's penalty. In v2, every match's threatScore feeds the IP rule THREAT_SCORE and the risk of /v2/inspect, whatever its action, so use action: null for a scored match without a verdict. Unlike penalize, a label-only entry doesn't override a block source; use an allow entry for that. The old routes are now /v2/threat-sources and /v2/threat-entries. See Threat intelligence.
full keys and management access
A full key reaches the management endpoints only through its security group's role, which only root can set. Migrated groups have no role, so their keys get 403 PERMISSION_REQUIRED on management endpoints until root assigns one. See Managing API keys.
Admin sign-in
v1 sessions don't carry over; everyone signs in again. After a migration, users keep their v1 passwords and OTP secrets.
Sign-in responses use the data envelope like every other endpoint. POST /v2/auth/login, /v2/auth/ldap, /v2/auth/login/otp, /v2/auth/login/passkey, and POST /v2/me/password return { "data": { "jwt": "…" } } instead of { "jwt": "…" }, and the second-factor step returns { "data": { "otp": true, "otpJwt": "…", "methods": […] } }. The jwt cookie is unchanged, so scripts that read the token from the body must read data.jwt.
OAuth
/v1/oauth/{provider}and its callback are now/v2/auth/oauth/{provider}and/v2/auth/oauth/{provider}/callback. Register the new redirect URI{base_url}/v2/auth/oauth/{provider}/callbackat each provider;base_urlis[auth] base_url, else[server.admin_ui] base_url(when the admin UI is enabled), else[server] base_url.authMethodsfrom/v1/app-config/authare inGET /v2/app-config, with aurlper provider andpasswordMinLength.- Only
redirectUrlis read (redirectUriis gone). It must be a path or a URL on the origin ofbase_url; anything else is400 VALIDATION_ERROR. - Azure needs a single-tenant
tenant_idGUID;commonandorganizationsstop startup. Existingazure:users still match. - Google needs
hosted_domain: Google Workspace accounts only. [auth] password_login = falseis enforced by the server:POST /v2/auth/loginreturns403 PASSWORD_LOGIN_DISABLEDfor every user, root included.
LDAP
/v1/auth/ldapisPOST /v2/auth/ldap.ALLOW_LDAPis gone; LDAP is on when[auth.ldap]is present. TheSSO_LDAPquery options are separate keys, and the group options are now enforced; see LDAP options.- Usernames are stored as
ldap:<lowercased username>(v1: as typed).migratelowercases them and skips a later duplicate, such asldap:JDoenext toldap:jdoe, with a warning. - An empty password is refused without contacting LDAP, and the username is escaped in the bind DN.
| Situation | v1 | v2 |
|---|---|---|
| Wrong credentials | 403 INCORRECT_PASSWORD or LDAP_FAILED | 401 INVALID_CREDENTIALS |
| Server or configuration fault | LDAP_FAILED | 502 LDAP_FAILED |
User outside allowed_groups | — | 403 LDAP_NOT_ALLOWED |
| LDAP not configured | — | 404 NOT_FOUND |
See Admin sign-in & SSO.
Management API & scripts
Scripts and dashboards that call the v1 management API need new paths, and in several places new rules.
| v1 | v2 |
|---|---|
/v1/accounts*, /v1/users*, /v1/api-keys*, /v1/security-groups* | /v2/accounts*, /v2/users*, /v2/api-keys*, /v2/security-groups* (/v1/api-keys/_list → POST /v2/api-keys/_search) |
/v1/users/{id}/_disable_mfa | POST /v2/users/{id}/_disable_otp |
/v1/*/{id}/_restore | — (deleted records can't be restored) |
/v1/auth/*, /v1/me/logout | /v2/auth/*, POST /v2/auth/logout |
/v1/me/change_password | POST /v2/me/password |
/v1/logs/_search, /v1/stats | POST /v2/request-logs/_search, POST /v2/request-logs/_stats |
/v1/alerts/_search | POST /v2/alerts/_search (see Alerts) |
/v1/threat-list* | /v2/threat-entries* |
/v1/threat-sources/{id}/_force_update | POST /v2/threat-sources/{id}/_update |
/v1/training-data* | /v2/training-data* |
/v1/admin/snapshots/* | /v2/snapshots* |
/v1/admin/license | GET /v2/license |
/v1/admin/cluster | GET /v2/cluster/replicas |
/v1/admin/files* | /v2/remote-files* |
/v1/access-logs/_search, /v1/error-logs/_search | — (logins and management changes: POST /v2/audit-logs/_search) |
/v1/admin/env*, /v1/admin/purge, /v1/context/encrypt | — |
/v1/forms*, /v1/form-submissions*, /v1/submit/*, /v1/redirects*, /link/*, /v1/blobs/* | — (features removed) |
Behavior changes:
- Non-root users reach
/v2/training-data*,/v2/training-suggestions*,/v2/request-logs*,/v2/security-groups*, and/v2/api-keys*according to their role (403 PERMISSION_REQUIRED,403 READ_ONLY_ROLE,404 NOT_FOUND). See Accounts, users & roles. - The
training_suggestionspermission is removed; suggestions are part oftraining_data. Creating a role with it returns400 UNKNOWN_FEATURE. POST /v2/security-groups/_searchandPOST /v2/api-keys/_searchrequirefilter.accountId, for root too.- An API key's
secretisnullfor callers withoutapi_keyswrite access. - Dashboards that called the detection endpoints with a session token must use an account's
restrictedorfullkey (Authentication).
The full API is in the API reference.
Operations
- Configuration. Environment variables are replaced by
sentinel.toml. See Config mapping. - Ports and listeners. The main API listens on
3000(v1 image:8080). The admin UI is off by default and has its own listener on127.0.0.1:3002. A widget-only listener ([server.public_api], port3003) and a Prometheus listener (3001) are optional. See Listeners & reverse proxy. - Health and metrics.
/.live,/.ready, and/v1/pingare gone. ProbeGET /(200 {"ok":true}), which answers once the server listens, after the schema migration and the first storage probe. Update KuberneteslivenessProbe/readinessProbepaths and load balancer health checks.GET /.healthis served on the main listener only. Itschecksarekv,db, andclickhouse(v1:redis,database,clickhouse), with notimestamporversion.MONITORING_HTTP_CREDENTIALSdoesn't apply to it; access is by client IP,[server] health_allowed_ips, private networks by default. Don't use it as a probe: a shared storage outage fails every replica at once. See Health endpoint./.metricsis the[prometheus]listener, withaltcha_sentinel_*metrics./.logsis gone: read the process output ([log] format = "json") or export traces with[telemetry].
- Allowed hosts.
ALLOWED_HOSTSisallowed_hosts, set per listener. On the API listeners it checks only/v2, soGET /andGET /.healthanswer any host. A request to another host gets421 Misdirected Request. See Allowed hosts. - Privacy.
[privacy] anonymize_ipis off by default, so request logs store full client IPs unless you turn it on. It also covers audit logs, alerts, and log lines; threat entries keep full IPs. - Databases. Supported versions are PostgreSQL 16 or later, MySQL 8.0.13 or later, MariaDB 11.4 LTS or later, SQL Server 2022 or later, and Oracle 21c or later; SQLite is bundled. MariaDB uses the
mariadb://scheme and older MariaDB versions stop startup; amysql://URL refuses a MariaDB server. LibSQL/Turso and Turbolite aren't supported. Database TLS options are query parameters of[database] urland take file paths, not PEM contents. See Database and Config mapping. - Redis Sentinel. The
REDIS_SENTINEL_*variables are the[redis.sentinel]table. Sentinel addresses areredis://orrediss://URLs carrying the Sentinel credentials, and one TLS setting covers both the Sentinels and the master. See Config mapping. - Private CAs.
TLS_EXTRA_CA_CERTSis the top-leveltls_extra_ca_certskey. It is trusted by every outbound TLS connection except Oracle. Per-connection CAs are[redis] tls_ca,[clickhouse] tls_ca,[auth.ldap] tls_ca, and the database URL's CA parameter. - Storage. Local file storage is removed. Snapshots and EML attachment uploads need
[storage]withs3orazure. - ClickHouse. v2 writes to a new
request_logstable and doesn't read v1'slogstable. The TLS variables become[clickhouse] tls_ca,tls_cert, andtls_key, which need anhttps://url. To keep old logs, copy them.
Alerts
Alerts come from the rules brute_force, user_brute_force, verification_failures, cpu, memory, and server_errors, plus rules for licenses, releases, API key misuse, remote file downloads, and database or KV outages. v1's INCORRECT_PASSWORD and rate-limit alerts are gone; repeated authentication failures and rate-limit trips feed threat signals instead.
| v1 field | v2 field | Notes |
|---|---|---|
type | rule | |
triggered | occurrences | Repeats count onto one alert per rule, account, subject, and [alerts] cooldown window (v1: one per day). |
createdAt, lastTriggeredAt (Unix seconds) | time, lastTime (RFC 3339) | |
data | details | |
severity (0, 1, 2) | severity (low, medium, high) | |
id | id | A string, alr_…. |
apiKeyId, ip, device, network, penalty, triggerId | — | Removed. A login alert's IP is its subject. |
Search filters: severity takes one value, timeStart/timeEnd are from/to (RFC 3339), and rule replaces type; apiKey, ip, message, and search are gone. Root may omit filter.accountId (every alert) or pass null (system-wide alerts); other users need the alerts permission in the account.
New: delivery by webhook ([[alerts.webhooks]]), email ([alerts.email]), and web push ([alerts.push]). See Alerts.
Data
- Snapshots. v1 snapshots (
.tgz,.tgz.age) can't be restored directly; restore returns400 INVALID_SNAPSHOT. Convert them withaltcha-sentinel migrate. See Migrating data. - Not migrated. Forms and submissions, redirects, alerts, access and error logs, automatic threat entries, OAuth tokens, and Redis data. The full list is on Migrating data.
- Training data arrives watch-only (weight
0). It has no effect until you review and raise the weights. - Device identifiers. The EDK formula and the header hash changed. v1 and v2 values never match, and rate-limit counters and penalties start empty.
- HIS scores aren't comparable with v1: feature groups are normalized weighted means, features without enough samples are skipped, keyboard-plus-mouse input is no longer penalized, and integrity checks are new. Re-tune
his.blockThresholdinmonitormode.