Console guide

Sites and setup health #

The console lists your sites with a status badge, the first problem that applies, and a button to the place that fixes it. Search by name, public key or origin, and show only the sites that need attention, the active ones, or the paused and locked-down ones.

Install wizard #

A site's Install tab walks through four steps and ticks each one when BlockAlt sees it done:

1. Verify your hostnames. Add the TXT record _blockalt.<hostname> with the value shown, then select Check DNS. When the check fails, the console says what it found: no record, other values (with the value expected), a timeout or a DNS server error.
2. Install the browser script. The snippet pins the script's integrity hash and every key of GET /v1/keys. The default is the HTML form mode: mark each form with data-blockalt-action, and the script fills a hidden blockalt-token field just before each submit. The JavaScript API variant calls execute() in your submit handler. Both get a fresh token for every attempt, never at page load.
3. Verify on your server. Samples for Node.js (with or without @blockalt/server), Python, PHP, Go, Ruby, Java, C# and curl, already filled in with your hostname and first action. The secret goes in BLOCKALT_SECRET on your server.
4. See the first verification. The page checks every few seconds and turns green at the first accepted verification. Meanwhile it shows whether your pages get tokens, whether your backend calls siteverify and why recent calls were refused.

Send a test verification runs the whole flow in your browser with the public test keys: real proof of work, then siteverify with the test secret. It never touches your site's data and is never billed.

Rules and protection states #

Protection state has three explicit choices, each confirmed before it applies. A switch is published at once as a new version: immediately at siteverify, and in visitors' pages within about five minutes.

See pause and lockdown for when to use each. While a priced workspace has used its free allowance and has no credit, its sites pass unchecked with the reason unpaid, except that lockdown and blocked actions keep refusing.

Confirming changes. Pausing or locking down protection (also by publishing a version that does), creating or revoking a server key, deleting a site and adding or deleting a notification destination need a second factor entered in the last 15 minutes; the console asks for a code or a passkey and then makes the change. Resuming protection, drafts, renaming and alert rules do not.

If BlockAlt support suspends a site or the workspace for abuse, the site's badge reads Suspended by BlockAlt, the console shows support's note, and every action is refused with the reason suspended (never billed) whatever the state you chose. Only support can lift a suspension: reply to the email you received. Deleting a suspended site does not lift it: while it lasts, no other site, in this workspace or another, can verify the hostnames it used (hostname_suspended).

The rules are drafted, reviewed and published:

• Allowed origins: exact origins, or a one-level wildcard such as https://*.example.com (see installation).
• Actions and, per action, Block: a blocked action is refused with rule_blocked while the others keep working.
• Work difficulty from 8 to 16 bits. The slider shows the expected solve time on a desktop and on a low-end phone, measured in Chromium. Adaptive difficulty adds bits for a visitor network that asks for many challenges, and for everyone during a surge.
• Requests per minute per visitor network (an IPv4 address or an IPv6 /64). One protected action uses two requests.

Saving creates a draft. Versions lists every version with what changed from the one before; before publishing, the console shows what changes compared with the published version, including a protection state change. A version saved with a difficulty above 16 (older releases allowed up to 20) is published at 16, and the console says so.

Alerts for this site set the thresholds of its alerts: refused verifications a minute of tokens issued for the site (default 20), refused browser requests a minute (default 1,000; anyone holding the public key can cause them) and, off by default, an alert when no verification succeeds for 1 to 72 hours. Leave a number empty to turn that alert off.

Server keys #

The Keys tab lists each server key with its name, the start of its secret (ba_sk_ and six characters; the full secret is shown once, at creation), when it was created and when it was last used (updated at most once a minute). A site can have up to ten active keys; the list also shows the 20 most recently revoked ones.

To rotate a key without downtime: create a new key, deploy it to your backend, check that its Last used changes, then revoke the old key. The console guides each step. The last active key of a site cannot be revoked, by the console or the API: create its replacement first.

Decisions and analytics #

The Overview tab charts the decisions of the last 7, 30 or 90 days: accepted (billable), refused by siteverify and allowed unchecked (paused or unpaid), plus the refusals in the browser before a token was issued. It also shows why siteverify refused, the top actions and hostnames, and which script versions your pages load, with a warning when visitors still use an older script. Every chart has a table view. Daily counts are kept long term; Export CSV downloads them.

The Decisions tab lists every server verification of a token issued for the site in the last seven days, newest first, filtered by outcome, reason and action, with an explanation of each reason. Tokens BlockAlt did not issue for the site (forged, malformed, empty, expired or another site's), which anyone can send through your forms, are counted per minute and reason instead (Tokens not issued for this site), like the browser refusals; they are included in the Overview and the install check, and raise no refusal alert. Export CSV downloads the decisions matching the filters. Only counts, reasons, actions and hostnames are kept: no visitor data.

Notifications #

Alerts go to the destinations on the Notifications page: email to the workspace's owners and admins (or every member) with a verified address, Slack, Discord, or a signed HTTPS webhook. Each destination shows when it last received an alert and its recent failed deliveries; one failing five times in a row is paused, and enabling it again retries at once.

Send test sends a test alert to one destination, or to all of them; with no destination, the console says so instead of queuing nothing. Up to ten destinations can be enabled at once and 25 kept; disabled ones do not count toward the ten. Deleting a destination stops its queued deliveries and erases its URL and signing secret.

Alerts name the site and link to it. They are sent for refusal bursts above the site's thresholds and, when enabled, when a site's integration goes silent.

Renaming and deleting a site #

Rename a site, or delete it, from the bottom of its Rules tab. Site and destination names appear in emails and alerts, so they are one line of at most 100 characters without a web address (:// or www.). Deleting asks you to type the site's name. A deleted site stops at once: its keys are revoked (invalid_secret), pages using its public key are refused, and it disappears from your sites. Its recorded decisions and usage are kept.