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, return403 LICENSE_NOT_ACTIVE. An activation key needs outbound access to the license server. If you downloaded a license file instead, mount it and usefile = "/home/nonroot/sentinel.license"in place ofkey;keyandfilecan'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, port3002. See[server.admin_ui]. - Root password. On first start, Sentinel creates the
rootuser 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
3000serves the API, including the widget endpoints. Port3002serves the admin UI. - v2 images are tagged by version,
2.0.0-beta.xduring the beta. Use the newest beta tag;lateststill 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:
- Open Dashboard. In the Get started card, click Quick setup. The card appears while the account has no security group or no API key.
- Review the Quick setup dialog. It creates a security group named
Websitewith Public access and the Recommended template, and an API key namedWebsitewith request logging on. - Click Create.
- 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-libimport { 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:
| HTTP | Code | Meaning |
|---|---|---|
| 403 | LICENSE_NOT_ACTIVE | No active license; data.status says why. Check [license] and the server log. |
| 401 | API_KEY_REQUIRED | The challenge URL has no apiKey, or the key doesn't start with key_. |
| 403 | BEARER_AUTH_PUBLIC_API_KEY | The key's security group isn't public. |
Next steps
- Concepts: how accounts, API keys, security groups, and scoring fit together.
- Install: production requirements, then Install with Docker.
- Server configuration: the configuration file, secrets, and listeners.
- Use cases: recommended rules and backend code for forms, sign-ups, and logins.
- Production checklist: what to change before you go live.