Skip to main content
ALTCHA®

Upgrading from Sentinel v1

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:

PageUse it for
This pageThe order of work, and what replaces removed features.
Breaking changesWhat changes for widgets, backends, security groups, sign-in, and operations.
Migrating dataConverting a v1 snapshot, restoring it, and copying ClickHouse logs.
Config mappingEvery 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.
  • 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.
  • 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 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.

Checklist

Step 1 — Get a v2 license

Sentinel v2 needs a Sentinel V2 license. Register at ALTCHA Cloud 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 and Plans & Licensing.

Step 2 — Write the configuration

Translate your v1 environment into sentinel.toml with Config mapping. Watch the 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:

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

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:

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.

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.

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 and Managing 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:

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

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, Verifying submissions, and Backend detection 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 and Admin sign-in & SSO.

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.

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.

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.

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 v2Use instead
Forms (/v1/submit/:slug) and form submissionsHost your own form endpoint and protect it with the widget plus verification of verificationData. See Contact & lead forms.
Links and redirectsNo replacement.
Autopilot and the adaptive code challengeThe Recommended preset, or set rules conditioned on penalty, risk, or signal. See Security presets.
AI security rules (set ai) and AI providersThe AI decider: classifier.ai, classifier.aiPurpose, classifier.aiInstructions.
Context override (/v1/context/encrypt)No replacement. Pass signed values with custom parameters (params.*).
Local file storage and /v1/blobsObject storage ([storage], S3 or Azure). EML attachments are returned inline below the size limit.
Environment-variable configurationsentinel.toml with ${VAR} and ${file:/path} expansion. See Config mapping.
Widgets up to 2.x, SHA challenges, X-Altcha-ConfigWidget v3 or later.
The penalize threat actionaction: null with a threatScore, which feeds the THREAT_SCORE rule.
/.ready, /.live, /v1/ping, /.logs, /.metricsGET / 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.
Password and rate-limit alertsThreat signals, and the new alert rules. See Alerts.
Access and error logsAudit logs and the server log.
LibSQL/Turso, TurboliteA supported database and Redis. See Databases & KV store.
The 30-day trial without a licenseA 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.

Start typing to search...

↑ ↓ Navigate ↵ Select