Skip to main content
ALTCHA®

Get started with Sentinel

This guide takes you from nothing to a verified widget submission in about 15 minutes. You run Sentinel locally in Docker, sign in to the admin UI, create an API key, protect a form, and see the result in the request logs.

Prerequisites

  • Docker on amd64 or arm64.
  • A Sentinel trial license. Register at ALTCHA Cloud and create a Sentinel V2 trial license in the Licenses section as an activation key (SENT-…). This guide uses the key; a license file needs the deployment ID of a running Sentinel first (see Licensing).
  • A web page with a form, and a backend that handles its submissions.

Step 1 — Write a configuration file

Sentinel reads its settings from sentinel.toml. Create a working directory with this file:

# sentinel.toml

[license]
key = "${SENTINEL_LICENSE_KEY}"   # SENT-… activation key, read from the environment

[server.admin_ui]
enabled = true
host = "0.0.0.0"                  # listen on all interfaces inside the container

[bootstrap]
root_password = "${ROOT_PASSWORD}"   # used on first start only
  • License. Without an active license, Sentinel starts, but the widget and detection endpoints, including /v2/challenge, return 403 LICENSE_NOT_ACTIVE. An activation key needs outbound access to the license server. If you downloaded a license file instead, mount it and use file = "/home/nonroot/sentinel.license" in place of key; key and file can't be combined. See Licensing.
  • Admin UI. The admin UI is off by default and binds to 127.0.0.1, which isn't reachable from outside a container. It runs on its own listener, port 3002. See [server.admin_ui].
  • Root password. On first start, Sentinel creates the root user with this password (at least 8 characters). The setting is ignored once a user exists. See [bootstrap].

Everything else uses its default: an embedded SQLite database and key-value store in the data directory, and secrets generated into data/secrets.json on first start. This is fine for a trial; for production, see Install.

Step 2 — Start Sentinel

Run the image with the configuration file and a volume for the data directory. The container's working directory is /home/nonroot, so the file goes to /home/nonroot/sentinel.toml and the data to /home/nonroot/data:

docker run -d --name sentinel \
  -p 3000:3000 -p 3002:3002 \
  -e SENTINEL_LICENSE_KEY='SENT-…' \
  -e ROOT_PASSWORD='choose-a-long-password' \
  -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \
  -v sentinel-data:/home/nonroot/data \
  ghcr.io/altcha-org/sentinel:2.0.0-beta.1
  • Port 3000 serves the API, including the widget endpoints. Port 3002 serves the admin UI.
  • v2 images are tagged by version, 2.0.0-beta.x during the beta. Use the newest beta tag; latest still points to Sentinel v1. See Install for the available tags.

Check that the server is up:

curl http://localhost:3000/
{"ok":true}

The log shows the license and the root user:

docker logs sentinel 2>&1 | grep -E 'licensed to|root user'

Step 3 — Sign in to the admin UI

Open http://localhost:3002 and log in with the username root and the password from step 1.

The root user is a member of the Default Account that Sentinel creates on first start. Accounts, API keys, and security groups belong to an account; see Accounts & users.

Step 4 — Create a security group and an API key

The widget authenticates with a public API key. The key's security group sets its access level and the rules every request must pass. Create both in one step:

  1. Open Dashboard. In the Get started card, click Quick setup. The card appears while the account has no security group or no API key.
  2. Review the Quick setup dialog. It creates a security group named Website with Public access and the Recommended template, and an API key named Website with request logging on.
  3. Click Create.
  4. Copy the Challenge URL and the API key secret from Your API key is ready. The secret is also shown later on the API Keys page.

The Recommended preset blocks IPs listed by threat intelligence, rate-limits each device, and gives risky or misbehaving clients a code challenge and a harder proof-of-work. To create the group yourself instead, use Security Groups → Create security group, set Access to public, and apply Recommended from the Templates tab of the rules editor. See Security groups and API keys & access levels.

Check that the key serves challenges:

curl -i 'http://localhost:3000/v2/challenge?apiKey=key_…'

The response is 200 with a challenge whose configuration.verifyUrl is /v2/verify. Because curl is a command-line client, the Recommended preset escalates it, so this response also contains a codeChallenge; browsers normally get a plain proof-of-work.

Step 5 — Add the widget to your form

Load the widget script, then set the widget's challenge attribute to the challenge URL you copied:

<form method="POST" action="/submit">
  <input type="email" name="email" required>
  <altcha-widget
    challenge="http://localhost:3000/v2/challenge?apiKey=key_…"
  ></altcha-widget>
  <button type="submit">Send</button>
</form>

Full setup instructions (npm install, CDN script, configuration options) are on the Widget Integration page.

The admin UI builds the challenge URL from the listener widgets call: the main API on port 3000 here, or [server.public_api] when you enable it, and that listener's base_url when set. In production, set base_url so the URL uses Sentinel's public address; see Listeners & reverse proxy. The widget sends the solution to /v2/verify on the same host and adds the signed result to the form as the altcha field. Widget options are on the widget integration page; Sentinel-specific options are in Embed the widget.

Step 6 — Verify the submission on your backend

The altcha field passes through the browser, so your backend must check its signature with the API key secret before it trusts the submission. In Node.js, install altcha-lib 2.9.0 or later:

npm install altcha-lib
import { verifyServerSignature } from 'altcha-lib';

// `altcha` is the submitted form field; `secret` is the API key secret (sec_…).
export async function verifyAltcha(altcha, secret) {
  try {
    const { verified, verificationData } = await verifyServerSignature({ payload: altcha, hmacSecret: secret });
    return verified ? verificationData : null;
  } catch {
    return null; // tampered payload, e.g. an unsupported algorithm
  }
}

verifyServerSignature checks the signature, that Sentinel verified the solution, and that the payload hasn't expired. Reject the submission when verifyAltcha returns null. Otherwise, verificationData.classification is GOOD, NEUTRAL, or BAD, and you decide what to do with each. Keep the secret on your server, for example in an environment variable. For PHP, Python, Go, .NET and other languages, see the server libraries.

To prevent a payload from being reused, or to verify without the secret, call POST /v2/verify/signature with a restricted key instead; the libraries do that with their verifyServer function. See Verifying submissions.

Verify it works

Submit the form in a browser. Then open Logs in the admin UI: the API key's Challenge and Verify requests are listed with their status, result, client, and the security-group rules that matched.

Requests appear because Quick setup turned on request logging for the key (Verification: challenge and verify requests). A key's request logging is Off by default, so keys you create on the API Keys page log nothing until you change it. See Request logs.

If the widget shows an error instead, check the response of /v2/challenge in the browser's network panel and look up its code in Error codes. The usual ones:

HTTPCodeMeaning
403LICENSE_NOT_ACTIVENo active license; data.status says why. Check [license] and the server log.
401API_KEY_REQUIREDThe challenge URL has no apiKey, or the key doesn't start with key_.
403BEARER_AUTH_PUBLIC_API_KEYThe key's security group isn't public.

Next steps

Start typing to search...

↑ ↓ Navigate ↵ Select