# Breaking changes in v2

> **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 lists every v1 to v2 change that needs action, grouped by who it affects. Use it together with the [upgrade checklist](/docs/sentinel/v2/upgrade/). Configuration changes are listed per variable in [Config mapping](/docs/sentinel/v2/upgrade/config-mapping/); features that no longer exist are in [Removed features](/docs/sentinel/v2/upgrade/#removed-features).

| Audience | Read |
|---|---|
| Frontend developers | [License](#license-enforcement), [Widget & frontend](#widget--frontend) |
| Backend developers | [License](#license-enforcement), [Backend integrations](#backend-integrations) |
| Sentinel admins | [Security groups](#security-groups), [Admin sign-in](#admin-sign-in), [Management API & scripts](#management-api--scripts) |
| Operators | [Operations](#operations), [Data](#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](/docs/sentinel/v2/reference/errors/).

## 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](/docs/sentinel/v2/configure/licensing/) and [Plans & Licensing](/docs/sentinel/v2/plans/).

## 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`:

```html
<!-- 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](/docs/sentinel/v2/upgrade/migrate-data/), 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](#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](/docs/sentinel/v2/integrate/widget/#existing-v1challenge-integrations).

### 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](/docs/sentinel/v2/concepts/api-keys/).

### 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](/docs/sentinel/v2/features/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](#security-groups) and [Data](#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](/docs/sentinel/v2/concepts/api-keys/#credential-matrix).

```bash
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](#classifier). |
| `POST /v1/eml` | `POST /v2/eml` | See [EML](#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](#language). |
| `POST /v1/phishing` | `POST /v2/phishing` | See [Phishing](#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](#inspect). |
| `POST /v1/verify/signature` | `POST /v2/verify/signature` | See [Verifying submissions](#verifying-submissions). |

Each `/v2` response is wrapped in `{ "data": … }`. Schemas are in the [API reference](/sentinel-api-docs-v2.html).

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

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

```ts
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](/docs/sentinel/v2/integrate/verification/).

### `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](/docs/sentinel/v2/integrate/verification/#the-verificationdata-fields).

### Classifier

`POST /v2/classifier` returns the same categories, with these changes. Rule scores are in [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/).

- **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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/concepts/scoring/).

### 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 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-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)](/docs/sentinel/v2/features/email-analysis/) and [Classifier rules & scores](/docs/sentinel/v2/reference/classifier-rules/).

## Security groups

The [`migrate` command](/docs/sentinel/v2/upgrade/migrate-data/#how-security-group-rules-are-translated) 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](/docs/sentinel/v2/reference/rules/#set-fields).

### 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](/docs/sentinel/v2/reference/rules/#condition-fields).

### 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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/policies/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](/docs/sentinel/v2/upgrade/config-mapping/#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.

| 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](/docs/sentinel/v2/security/sign-in/).

## 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](#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](/docs/sentinel/v2/concepts/accounts-users/).
- 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](#authentication)).

The full API is in the [API reference](/sentinel-api-docs-v2.html).

## Operations

- **Configuration.** Environment variables are replaced by `sentinel.toml`. See [Config mapping](/docs/sentinel/v2/upgrade/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](/docs/sentinel/v2/configure/listeners/).
- **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](/docs/sentinel/v2/reference/configuration/#health-endpoint).
- `/.metrics` is the [`[prometheus]`](/docs/sentinel/v2/reference/configuration/#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](/docs/sentinel/v2/reference/configuration/#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](/docs/sentinel/v2/install/#database) and [Config mapping](/docs/sentinel/v2/upgrade/config-mapping/#database).
- **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](/docs/sentinel/v2/upgrade/config-mapping/#kv-store-redis).
- **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](/docs/sentinel/v2/upgrade/migrate-data/#copy-clickhouse-request-logs).

### 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](/docs/sentinel/v2/features/threat-intelligence/) 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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/upgrade/migrate-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](/docs/sentinel/v2/upgrade/migrate-data/#what-isnt-migrated).
- **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.
