# Upgrading from Sentinel v1

> **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).

Sentinel v2 is a rewrite, not an in-place update. Configuration moves from environment variables to a TOML file, security groups use a rules engine, the API moves to `/v2`, and some v1 features are gone. Run v2 alongside your v1 deployment, migrate your data and integrations step by step, then cut traffic over. Sentinel v1 remains supported for 18 months after v2 reaches general availability.

This section has four pages:

| Page | Use it for |
|---|---|
| This page | The order of work, and what replaces removed features. |
| [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/) | What changes for widgets, backends, security groups, sign-in, and operations. |
| [Migrating data](/docs/sentinel/v2/upgrade/migrate-data/) | Converting a v1 snapshot, restoring it, and copying ClickHouse logs. |
| [Config mapping](/docs/sentinel/v2/upgrade/config-mapping/) | Every v1 environment variable and its v2 key. |

## Before you start

Take stock of your v1 deployment. Each answer decides which steps below apply to you:

- **Widgets.** Which widget versions do your pages load? v2 needs widget v3 or later. Which API keys do they use, and are those keys' security groups `public`?
- **Backends.** How do your servers check the `altcha` payload: locally with the key secret, or by calling `/v1/verify/signature`? Which other endpoints do they call (`/v1/classifier`, `/v1/eml`, …), and with which keys?
- **Removed features.** Do you use Forms, redirects, Autopilot, AI security rules, or local file storage? See [Removed features](#removed-features).
- **Database and TLS.** Which database do you run, and which version? v2 supports 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; plan a database upgrade first if yours is older. Do connections use TLS with certificates from a private CA? See [Database](/docs/sentinel/v2/install/#database).
- **Admin sign-in.** Do admins sign in with OAuth or LDAP?
- **Logs.** Are request logs in ClickHouse?
- **Automation.** Do scripts or dashboards call the v1 management API?

Then read [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/) for the parts that apply.

## Plan the cutover

Run v1 and v2 side by side, each with its own database, until traffic has moved:

1. **Rehearse.** Migrate a v1 snapshot into v2 and test your widgets and backends against it, on a separate hostname.
2. **Migrate for real.** Freeze changes in v1's admin app, take the final snapshot, and migrate and restore it into v2.
3. **Switch.** Point widgets and backends at v2, at your DNS, load balancer, or in code.
4. **Keep v1** running and untouched until you are sure you won't roll back.

Every restore replaces the v2 database. Changes you make in v2 after a rehearsal restore, such as new keys or edited groups, are lost when you restore the final snapshot. Make such changes in v1 before the final snapshot where v1 allows it, or record them, for example as API calls, and repeat them after the final restore.

<Callout type="warning" title="Don't share v1's database">

Point v2 at a new database, or at a separate schema. v2 creates its own tables, and the v1 deployment must stay intact for rollback.

## Checklist

| # | Step | Who |
|---|---|---|
| 1 | [Get a v2 license](#step-1--get-a-v2-license) | Operator |
| 2 | [Write the configuration](#step-2--write-the-configuration) | Operator |
| 3 | [Set the secrets](#step-3--set-the-secrets) | Operator |
| 4 | [Convert the v1 snapshot](#step-4--convert-the-v1-snapshot) | Operator |
| 5 | [Restore it into v2](#step-5--restore-it-into-v2) | Operator, root |
| 6 | [Move widget keys to `public` groups](#step-6--move-widget-keys-to-public-groups) | Sentinel admin |
| 7 | [Switch the widget to `/v2`](#step-7--switch-the-widget-to-v2) | Frontend |
| 8 | [Update backends to Basic auth](#step-8--update-backends-to-basic-auth) | Backend |
| 9 | [Re-register OAuth redirect URIs](#step-9--re-register-oauth-redirect-uris) | Operator |
| 10 | [Check LDAP users](#step-10--check-ldap-users) | Sentinel admin |
| 11 | [Cut traffic over](#step-11--cut-traffic-over) | Operator |
| 12 | [Copy ClickHouse logs](#step-12--copy-clickhouse-logs) | Operator |
| 13 | [Decommission v1](#step-13--decommission-v1) | Operator |

## Step 1 — Get a v2 license

Sentinel v2 needs a Sentinel V2 license. Register at [ALTCHA Cloud](https://cloud.altcha.org/) and create one in the **Licenses** section, as an online key (`SENT-…`) or a license file. Without an active license, `/v2/challenge` and the other functional endpoints return `403 LICENSE_NOT_ACTIVE`, and without a usable one, v2 runs only on SQLite with one account, user, API key, and security group.

Check that the license covers your deployment: the database backend (`exotdb.backend.postgres`, …), `clickhouse`, `oauth`, `ldap`, `audit_logs`, and limits on instances, accounts, users, API keys, and security groups. See [Licensing](/docs/sentinel/v2/configure/licensing/) and [Plans & Licensing](/docs/sentinel/v2/plans/).

## Step 2 — Write the configuration

Translate your v1 environment into `sentinel.toml` with [Config mapping](/docs/sentinel/v2/upgrade/config-mapping/). Watch the [defaults that changed](/docs/sentinel/v2/upgrade/config-mapping/#defaults-that-changed): the main port is `3000`, `trusted_proxies` trusts no proxy when empty, IP anonymization is off, and the admin UI is off.

Validate the file before you start the server, in a one-off container of the v2 image:

```bash
docker run --rm \
-v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 doctor --config-only
```

See [The configuration file](/docs/sentinel/v2/configure/) and [Install](/docs/sentinel/v2/install/).

## Step 3 — Set the secrets

v2 has its own secrets: `[secrets] jwt_secret`, `altcha_hmac_secret`, and the new `encryption_key`. With embedded SQLite on one node they are generated on first start. With any other database, or more than one replica, set them explicitly and identically on every replica. You don't need v1's secret values.

Decide on the secrets before Step 4: `migrate` encrypts API key secrets with `encryption_key`, and the server must use the same key. See [Secrets](/docs/sentinel/v2/configure/secrets/).

## Step 4 — Convert the v1 snapshot

Take a main-database snapshot in v1 and convert it in the v2 image, with the same config file, secrets, and data volume as the v2 server:

```bash
mkdir -p migration && cp altcha-sentinel-2026-11-14T08_35_53.tgz migration/
sudo chown -R 65532 migration   # the image runs as uid 65532

docker run --rm \
-v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
-v "$PWD/secrets:/run/secrets:ro" \
-v sentinel-data:/home/nonroot/data \
-v "$PWD/migration:/migration" \
ghcr.io/altcha-org/sentinel:2.0.0-beta.1 \
migrate /migration/altcha-sentinel-2026-11-14T08_35_53.tgz --output-dir /migration
```

The command prints a warning for everything it couldn't translate. See [Migrating data](/docs/sentinel/v2/upgrade/migrate-data/).

## Step 5 — Restore it into v2

As root in the v2 admin UI, open **Snapshots → Restore from file** and upload the converted file. The restore replaces the database: afterwards, sign in with your v1 credentials. Then review the `migrate` warnings, the translated security-group rules, and the training data, which arrives with weight `0`. See [Review the result](/docs/sentinel/v2/upgrade/migrate-data/#step-4--review-the-result).

## Step 6 — Move widget keys to `public` groups

v2's widget endpoints accept only keys of `public` security groups. For every group that `migrate` warned about (`its API keys no longer work for the widget`):

- If the group's keys serve only widgets, change its **Access** to `public` in **Security Groups**.
- If a key serves both a widget and a backend, keep it for the widget in a `public` group, and give the backend a new `restricted` key in **API Keys**.

Full keys that automation uses on management endpoints need a `role` on their group, which only root can set. See [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/) and [Managing API keys](/docs/sentinel/v2/policies/api-keys/).

## Step 7 — Switch the widget to `/v2`

Upgrade pages to widget v3 or later, and change the challenge URL from `/v1/challenge` to `/v2/challenge`. Key ids stay the same:

```html
<altcha-widget challenge="https://sentinel.example.com/v2/challenge?apiKey=key_…"></altcha-widget>
```

If you can't change every page before cutover, set `[server] v1_compat = true`. v2 then also serves `/v1/challenge`, `/v1/challenge/audio/{file}`, `/v1/verify`, and `/v1/verify/signature`, for widgets v3 or later. Widgets up to 2.x don't work with v2 at all. See [Widget integration](/docs/sentinel/v2/integrate/widget/).

## Step 8 — Update backends to Basic auth

- **Remote verification.** Upgrade the server library (`altcha-lib` 2.9.0, `altcha-org/altcha` for PHP 2.4.0, `altcha` for Python 2.4.0, `altcha-lib-go` 2.5.0, `Altcha` for .NET 1.2.0, or later), point it at `/v2/verify/signature`, and pass a `restricted` key's id and secret. The body `secret` of v1 is rejected.
- **Local verification** with `verifyServerSignature` keeps working; update code that reads renamed fields such as `challengeAlgorithm` or `hisScore`.
- **Detection endpoints** (`/v2/classifier`, `/v2/eml`, `/v2/ip`, …) need a `restricted` or `full` key with Basic `key_…:sec_…`, and wrap their responses in `{ "data": … }`.
- **Management scripts** need the `/v2` paths.

See [Backend integrations](/docs/sentinel/v2/upgrade/breaking-changes/#backend-integrations), [Verifying submissions](/docs/sentinel/v2/integrate/verification/), and [Backend detection APIs](/docs/sentinel/v2/integrate/backend-apis/).

## Step 9 — Re-register OAuth redirect URIs

The OAuth callback moved to `/v2/auth/oauth/{provider}/callback`. At each identity provider, register `{base_url}/v2/auth/oauth/{provider}/callback`, where `base_url` is the admin UI's public URL. Azure needs a tenant GUID and Google a `hosted_domain`. See [OAuth](/docs/sentinel/v2/upgrade/breaking-changes/#oauth) and [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/).

## Step 10 — Check LDAP users

v2 stores LDAP users as `ldap:` plus the lowercased username. `migrate` lowercases existing users and skips a later duplicate that differs only by case, with a warning. For each skipped user, move their account memberships to the user that was kept. LDAP settings are now separate `[auth.ldap]` keys; see [LDAP options](/docs/sentinel/v2/upgrade/config-mapping/#ldap-options).

## Step 11 — Cut traffic over

1. Freeze changes in v1's admin app.
2. Take the final v1 snapshot, convert it, and restore it into v2 (Steps 4 and 5). Repeat any v2-only changes from Steps 6 and 10.
3. Switch traffic: point the Sentinel hostname at v2, or deploy the widget and backend changes from Steps 7 and 8.
4. Watch **Logs** in the v2 admin UI and your error rates. Look up unexpected codes in [Error codes](/docs/sentinel/v2/reference/errors/).

To roll back, point traffic at v1 again. Data created in v2 after the cutover, such as new keys and request logs, doesn't flow back to v1.

## Step 12 — Copy ClickHouse logs

If v1 wrote request logs to ClickHouse, copy them into v2's `request_logs` table once v1 no longer receives traffic, so the copy includes its last logs. Each month must be inserted exactly once. See [Copy ClickHouse request logs](/docs/sentinel/v2/upgrade/migrate-data/#copy-clickhouse-request-logs).

## Step 13 — Decommission v1

When v2 has run without problems for long enough that you won't roll back, stop v1. Keep a last v1 snapshot and its age key, if you used one: it is the only copy of data that v2 doesn't migrate, such as form submissions and alerts.

## Removed features

| Removed in v2 | Use instead |
|---|---|
| Forms (`/v1/submit/:slug`) and form submissions | Host your own form endpoint and protect it with the widget plus verification of `verificationData`. See [Contact & lead forms](/docs/sentinel/v2/use-cases/forms/). |
| Links and redirects | No replacement. |
| Autopilot and the `adaptive` code challenge | The **Recommended** preset, or `set` rules conditioned on `penalty`, `risk`, or `signal`. See [Security presets](/docs/sentinel/v2/policies/presets/). |
| AI security rules (`set ai`) and AI providers | The [AI decider](/docs/sentinel/v2/features/ai-decider/): `classifier.ai`, `classifier.aiPurpose`, `classifier.aiInstructions`. |
| Context override (`/v1/context/encrypt`) | No replacement. Pass signed values with [custom parameters](/docs/sentinel/v2/integrate/parameters/) (`params.*`). |
| Local file storage and `/v1/blobs` | [Object storage](/docs/sentinel/v2/configure/storage/) (`[storage]`, S3 or Azure). EML attachments are returned inline below the size limit. |
| Environment-variable configuration | `sentinel.toml` with `${VAR}` and `${file:/path}` expansion. See [Config mapping](/docs/sentinel/v2/upgrade/config-mapping/). |
| Widgets up to 2.x, SHA challenges, `X-Altcha-Config` | Widget v3 or later. |
| The `penalize` threat action | `action: null` with a `threatScore`, which feeds the `THREAT_SCORE` rule. |
| `/.ready`, `/.live`, `/v1/ping`, `/.logs`, `/.metrics` | `GET /` for liveness and readiness probes, the `[prometheus]` listener for metrics, and the process output for logs. `GET /.health` remains, with changed checks. See [Breaking changes](/docs/sentinel/v2/upgrade/breaking-changes/#operations). |
| Password and rate-limit alerts | Threat signals, and the new alert rules. See [Alerts](/docs/sentinel/v2/operations/alerts/). |
| Access and error logs | [Audit logs](/docs/sentinel/v2/operations/audit-logs/) and the server log. |
| LibSQL/Turso, Turbolite | A supported database and Redis. See [Databases & KV store](/docs/sentinel/v2/configure/databases/). |
| The 30-day trial without a license | A trial license from ALTCHA Cloud. |

## What isn't migrated

Forms and their submissions, redirects, alerts, access and error logs, automatic threat entries, disabled account features, OAuth tokens, Redis data, and request logs that v1 kept in ClickHouse (copied separately in Step 12). Training data is migrated but inactive until you raise its weights. See [Migrating data](/docs/sentinel/v2/upgrade/migrate-data/#what-isnt-migrated).

## Related

- [Get started](/docs/sentinel/v2/get-started/): a fresh v2 install, to explore before you migrate.
- [Production checklist](/docs/sentinel/v2/security/production-checklist/): what to check before cutover.
- [Release notes](/docs/sentinel/releases/)
