Skip to main content
ALTCHA®

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.

AudienceRead
Frontend developersLicense, Widget & frontend
Backend developersLicense, Backend integrations
Sentinel adminsSecurity groups, Admin sign-in, Management API & scripts
OperatorsOperations, 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 /v2 routes with 403 BACKEND_NOT_LICENSED, and extra replicas get 503 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] key or file), 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 pathServed as
GET /v1/challengeGET /v2/challenge
GET /v1/challenge/audio/{file}GET /v2/challenge/audio/{file}
POST /v1/verifyPOST /v2/verify
POST /v1/verify/signaturePOST /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 code on /v2/verify (INCORRECT_CODE) burns the challenge; the widget fetches a new one.
  • A code solved less than [code_challenge] min_solve_time (default 4s) after issue, or before the spoken code ends once the audio was fetched, fails with TOO_FAST and burns the challenge.
  • The audio endpoint waits [code_challenge] audio_delay (default 3s), is limited per client IP by audio_rate_limit (default 10/5m), and answers only the network the challenge was issued to (the same IPv4 address or IPv6 /64); otherwise 404 NOT_FOUND.
  • The image uses the standard style 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, and codeChallenge.audioLanguages limits 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/challenge answers with a redirect and the widget posts its interaction data to POST /v2/challenge. The GET isn't counted against rule rate limits or logged; the POST is (v1 exempted both).
  • In relaxed and strict mode, a blocked visitor gets 403 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

Changev1v2
restricted keysId alone acceptedId and secret, Authorization: Basic base64("key_…:sec_…"), like full keys
Only the id of a restricted/full key403 BEARER_AUTH_NO_FULL_API_KEY (full only)403 BEARER_AUTH_PUBLIC_API_KEY
A public key with Basic403 BASIC_AUTH_FULL_API_KEY403 BASIC_AUTH_NON_PUBLIC_API_KEY
Detection endpoints with a session tokenAcceptedRefused: 401 API_KEY_REQUIRED without a key, 403 NON_PUBLIC_API_KEY_REQUIRED with a public key
accountId in the bodySelected the accountIgnored: 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

v1v2Notes
POST /v1/classifierPOST /v2/classifierSee Classifier.
POST /v1/emlPOST /v2/emlSee EML.
POST /v1/ipPOST /v2/ipnetworks (a list) replaces network; new errors lists failed resolver providers.
POST /v1/languagePOST /v2/languageSee Language.
POST /v1/phishingPOST /v2/phishingSee Phishing.
POST /v1/similarityPOST /v2/similarityMatches the account's training groups.
POST /v1/threatPOST /v2/threat
POST /v1/threat/reportPOST /v2/threat/_reportaction is the IP's verdict after the report; use limitExceeded to tell whether this report listed the IP.
POST /v1/timezonePOST /v2/time-zone
POST /v1/user-agentPOST /v2/user-agent
GET /v1/inspectGET /v2/inspectSee Inspect.
POST /v1/verify/signaturePOST /v2/verify/signatureSee 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.

  • secret in the body is rejected with 400 VALIDATION_ERROR.
  • A payload signed by another account's key returns verified: false with reason: API_KEY_NOT_ALLOWED.
  • verificationData keeps id, fieldsHash, device.edk, and params.* as strings. v1 turned numeric-looking values, such as the zip code 01234, into numbers.
  • The /v1/verify/signature alias (with v1_compat) needs no credentials and, like v1, answers WRONG_API_KEY_SECRET when a non-empty secret isn't the payload key's.

Upgrade your server library to a version whose verifyServer supports v2, and pass a restricted key:

LanguageLibraryVersion
Node.jsaltcha-lib2.9.0
PHPaltcha-org/altcha2.4.0
Pythonaltcha2.4.0
Goaltcha-lib-go2.5.0
.NETAltcha1.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 fieldv2 fieldNotes
challengeAlgorithmchallenge.algorithmAlso removed from the unsigned base64 payload JSON.
hisScorehis.automationThe bot probability. his.score is now the sum of the HIS rules.
hisAssistivehis.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.edk uses a new formula, so v1 and v2 EDKs never match. New rules CLI and LIBRARY flag command-line clients and HTTP libraries. The ALTCHA native widgets (altcha-app, altcha-rn, altcha-flutter) are trusted apps and don't trigger USER_AGENT_HEADER_UNCOMMON, CLI, or LIBRARY (security-group setting classifier.trustedApps). The device BOT rule scores only a verified Web Bot Auth signature.
  • IP. New ip rule BOT for IPs on bot and crawler lists. The IP's threat score, which v1 added to ip.score, is now the THREAT_SCORE rule: listed in triggeredRules and reasons, and switchable with enableRules/disableRules. ip also carries the /v2/ip fields (networks, threats, action, threatScore, …).
  • Location. Keeps its rules and fields. timeZone is null (not omitted) when unknown, and the top-level timeZone is null rather than an object of nulls. The high-risk list is the security-group setting classifier.highRiskCountries; there is no server-wide list.
  • Text. A built-in spam and profanity filter scores the body's text (else the text of fields), 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's languages, else the detected language, else the Accept-Language header.
  • Phishing. URL_PHISHING lists URLs in text.phishing (url, phishId, target, submittedAt) instead of rules.URL_PHISHING.tokens. It scores even with URL disabled, matches URLs without a scheme and in markup, and raises the top-level score to at least 2 (BAD).
  • Injection. v1's text rules SQL_INJECTION and HTML_INJECTION are now the injection category: SQL_INJECTION, HTML_INJECTION, EMAIL_HEADER_INJECTION, TEMPLATE_INJECTION, and NOSQL_INJECTION. They scan each field's key and value, the body's text and email, and list their matches. A triggered injection rule raises the top-level score to at least 2 (BAD).
  • Similarity. The SIMILARITY:{group} rules and the body's similarity array are replaced by the similarity category: SIMILARITY (semantic match), NEAR_DUPLICATE, and the new CAMPAIGN. Semantic matching needs [similarity] provider (default none). Groups come from the security-group setting classifier.similarityGroups or the body's similarityGroups. A match whose best sample has weight 1 or more raises the score to at least 2 (BAD).

See Classifier.

Inspect

  • autopilotThreat is removed.
  • penalty is 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 (except CHALLENGE_EXPIRED), and penalty.add rules do. It expires [penalty] ttl (default 30m) after its last increase.
  • risk is device.score + network.score + location.score, capped at 10 and rounded to one decimal, and the root triggeredRules lists 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.headerEntropy is null (was 0) without a headerEntropy.limit. Past the limit, /v2/challenge and /v2/inspect answer 429 HEADER_ENTROPY.
  • network has the /v2/ip fields plus timedOut and the network rules' rules, score, and triggeredRules. networks (a list) replaces network.
  • device.headerHash is the first 8 bytes of SHA-256 (was xxh64), so v1 and v2 hashes differ.
  • The new timeZone query parameter enables TIMEZONE_MISMATCH.

See Scores, risk & penalty.

Language

  • The detector covers 30 languages (v1: 50). no covers Bokmål and Nynorsk; Serbian, Croatian, and Bosnian are one language, sh.
  • There is no en fallback. v1 answered en with probability 0.35 when the top probability was below 0.5; v2 returns the probabilities as detected, and languages: [] for a text without letters.
  • hints take up to 50 language codes of up to 35 characters (de-AT, nb); text takes up to 16000 characters.

Phishing

v1 fieldv2 fieldNotes
idphishId
info—Removed (the PhishTank detail link).
—urlThe 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-Upload needs a [storage] provider (s3 or azure); without one the request is 400 VALIDATION_ERROR. Local storage and /v1/blobs are removed. attachments[].contentUri is the native object URI (s3://bucket/key or the Azure blob URL) plus ?size=&type=&filename=; fetch it with your storage credentials. A failed upload is 502 STORAGE_ERROR.
  • Without the upload header, attachments up to X-Attachments-Size-Limit bytes (default 5000000) are returned inline as base64 content; larger ones have content: null.
  • Without X-Authenticate, the trusted Authentication-Results header is the topmost one (the receiving server's), not the bottommost.
  • New fields: authentication.DMARC, mail.links, triggeredRules, and attachments[].risks.
  • New rules include DMARC_ALIGNMENT, LINK_TEXT_MISMATCH, SUSPICIOUS_LINK, LINK_PHISHING, MESSAGE_ID_ANOMALY, DATE_ANOMALY, BULK_MAILER, HTML_ONLY, HIDDEN_TEXT, and ATTACHMENT_RISK.
  • The SPF client IP is the topmost Received header with a public IP. The classifier's IP rules use the sending server's IP (X-Smtp-Ip, else that Received IP), falling back to X-Originating-IP.
  • attachments[].checksum is SHA-256 (was MD5), inReplyTo is a string (was an array), and headers[].value is always the raw unfolded value.
  • The body limit is [eml] max_body_size (default 5000000 bytes); a larger body is 413 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 fieldv2 set fieldNotes
autopilot—Removed. Use the Recommended preset, or set rules conditioned on penalty, risk, or signal.
powVersion—Removed; only proof-of-work v2 exists.
algorithm, supportedAlgorithmspow.algorithmOne algorithm.
cost, counter, memoryCost, expirespow.cost, pow.counter, pow.memoryCost, pow.expirespow.expires takes a duration.
rateLimitrateLimit.limitsN/DURATION; the key goes in parentheses, e.g. 50/10m(key=edk).
key—Part of rateLimit.limits: (key=edk), (key=ip), or (key=uid).
rateLimitScoperateLimit.scopeaccount or apiKey.
classifyFieldsclassifier.fields
enableClassificationRules, disableClassificationRulesclassifier.enableRules, classifier.disableRules
highRiskCountriesclassifier.highRiskCountries
hishis.modeoff, monitor, relaxed, or strict; default off.
hisBlockThresholdhis.blockThreshold0.1–1, default 0.8.
hisHashTTLhis.hashTtl10m–7d, default 12h.
—his.penaltyNew: what relaxed and strict add to the penalty (default 1).
headerEntropyLimitheaderEntropy.limitN/DURATION, N 1–99, DURATION 1m–24h.
headerEntropyRiskFactorheaderEntropy.penaltyNow added to the penalty for each new header hash beyond the first, instead of weighting risk.
codeChallenge (true)codeChallenge.enabledtrue or false, default false.
codeChallenge (adaptive)—Removed. Put a condition on the rule instead, e.g. penalty >= 3.
codeChallengeAlphabetcodeChallenge.alphabet2–36 ASCII letters or digits, default 234579.
codeChallengeMinLength, codeChallengeMaxLengthcodeChallenge.lengthN or MIN-MAX within 4–8, default 5.
penaltypenalty.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 conditionv2 condition
hosting, proxy, tor, mobile = truenetwork = hosting, proxy, tor, or mobile
malicious = true, bot = truesignal = MALICIOUS, BOT
country = list:high_riskcountry = high_risk
penalty with a range such as 4-10Two 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}/callback at each provider; base_url is [auth] base_url, else [server.admin_ui] base_url (when the admin UI is enabled), else [server] base_url.
  • authMethods from /v1/app-config/auth are in GET /v2/app-config, with a url per provider and passwordMinLength.
  • Only redirectUrl is read (redirectUri is gone). It must be a path or a URL on the origin of base_url; anything else is 400 VALIDATION_ERROR.
  • Azure needs a single-tenant tenant_id GUID; common and organizations stop startup. Existing azure: users still match.
  • Google needs hosted_domain: Google Workspace accounts only.
  • [auth] password_login = false is enforced by the server: POST /v2/auth/login returns 403 PASSWORD_LOGIN_DISABLED for every user, root included.

LDAP

  • /v1/auth/ldap is POST /v2/auth/ldap.
  • ALLOW_LDAP is gone; LDAP is on when [auth.ldap] is present. The SSO_LDAP query options are separate keys, and the group options are now enforced; see LDAP options.
  • Usernames are stored as ldap:<lowercased username> (v1: as typed). migrate lowercases them and skips a later duplicate, such as ldap:JDoe next to ldap:jdoe, with a warning.
  • An empty password is refused without contacting LDAP, and the username is escaped in the bind DN.
Situationv1v2
Wrong credentials403 INCORRECT_PASSWORD or LDAP_FAILED401 INVALID_CREDENTIALS
Server or configuration faultLDAP_FAILED502 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.

v1v2
/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_mfaPOST /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_passwordPOST /v2/me/password
/v1/logs/_search, /v1/statsPOST /v2/request-logs/_search, POST /v2/request-logs/_stats
/v1/alerts/_searchPOST /v2/alerts/_search (see Alerts)
/v1/threat-list*/v2/threat-entries*
/v1/threat-sources/{id}/_force_updatePOST /v2/threat-sources/{id}/_update
/v1/training-data*/v2/training-data*
/v1/admin/snapshots/*/v2/snapshots*
/v1/admin/licenseGET /v2/license
/v1/admin/clusterGET /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_suggestions permission is removed; suggestions are part of training_data. Creating a role with it returns 400 UNKNOWN_FEATURE.
  • POST /v2/security-groups/_search and POST /v2/api-keys/_search require filter.accountId, for root too.
  • An API key's secret is null for callers without api_keys write access.
  • Dashboards that called the detection endpoints with a session token must use an account's restricted or full key (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 on 127.0.0.1:3002. A widget-only listener ([server.public_api], port 3003) and a Prometheus listener (3001) are optional. See Listeners & reverse proxy.
  • Health and metrics.
    • /.live, /.ready, and /v1/ping are gone. Probe GET / (200 {"ok":true}), which answers once the server listens, after the schema migration and the first storage probe. Update Kubernetes livenessProbe/readinessProbe paths and load balancer health checks.
    • GET /.health is served on the main listener only. Its checks are kv, db, and clickhouse (v1: redis, database, clickhouse), with no timestamp or version. MONITORING_HTTP_CREDENTIALS doesn'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.
    • /.metrics is the [prometheus] listener, with altcha_sentinel_* metrics. /.logs is gone: read the process output ([log] format = "json") or export traces with [telemetry].
  • Allowed hosts. ALLOWED_HOSTS is allowed_hosts, set per listener. On the API listeners it checks only /v2, so GET / and GET /.health answer any host. A request to another host gets 421 Misdirected Request. See Allowed hosts.
  • Privacy. [privacy] anonymize_ip is 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; a mysql:// URL refuses a MariaDB server. LibSQL/Turso and Turbolite aren't supported. Database TLS options are query parameters of [database] url and take file paths, not PEM contents. See Database and Config mapping.
  • Redis Sentinel. The REDIS_SENTINEL_* variables are the [redis.sentinel] table. Sentinel addresses are redis:// or rediss:// URLs carrying the Sentinel credentials, and one TLS setting covers both the Sentinels and the master. See Config mapping.
  • Private CAs. TLS_EXTRA_CA_CERTS is the top-level tls_extra_ca_certs key. 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] with s3 or azure.
  • ClickHouse. v2 writes to a new request_logs table and doesn't read v1's logs table. The TLS variables become [clickhouse] tls_ca, tls_cert, and tls_key, which need an https:// 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 fieldv2 fieldNotes
typerule
triggeredoccurrencesRepeats count onto one alert per rule, account, subject, and [alerts] cooldown window (v1: one per day).
createdAt, lastTriggeredAt (Unix seconds)time, lastTime (RFC 3339)
datadetails
severity (0, 1, 2)severity (low, medium, high)
ididA 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 returns 400 INVALID_SNAPSHOT. Convert them with altcha-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.blockThreshold in monitor mode.

Start typing to search...

↑ ↓ Navigate ↵ Select