Quickstart

1Step 1: Create your workspace #

Create an account, confirm your email address and set up an authenticator app. Both are required before you can add a site.

2Step 2: Add a site #

In the console, add a site with:

• Origins: the exact origins of the pages that will load the script, such as https://example.com and https://www.example.com, without paths. https://*.example.com covers one level of subdomains, such as preview deployments.
• Actions: one short name per protected action, such as signup, login or checkout. Letters, digits, _ and -, up to 64 characters.

You receive a public site key and a secret key.

3Step 3: Prove you own the hostname #

Add the TXT record shown in the console's Install tab, at _blockalt.<hostname>, then select Check DNS. Nothing else in your DNS changes. Until a hostname is verified, the script is refused with domain_unverified. The console guide describes every step of the Install tab.

4Step 4: Add the script and get a token at submit time #

Load the script with its integrity hash and add a hidden field to the form:

<script src="https://blockalt.click/v1/assets/blockalt.c8b2d9539dbbc932999adb0f51a36bddd4e99899f543e1505818841878cf9813.js"
  integrity="sha384-pblByFDqcJxRfhDh18GH3gRsWy9ZaS4AjDc6OpozzQqvkuYvyin+4BWcKXxA+bN8"
  crossorigin="anonymous"></script>
<script src="/js/signup.js" defer></script>

<form id="signup" method="post" action="/signup">
  <input name="email" type="email" required>
  <input name="blockalt-token" type="hidden">
  <button>Create account</button>
  <p class="error" role="alert"></p>
</form>

Then request the token in the submit handler, from your own JavaScript file:

const protection = BlockAlt.create({
  siteKey: "ba_pk_your_public_site_key",
  apiUrl: "https://blockalt.click",
  // Every key of GET /v1/keys (configPublicKeys), standby keys included.
  configPublicKeys: ["MCowBQYDK2VwAyEAXmYdcBh/jf+z+0H+hs2QvZ9UG4PBgkRvHX/JuXyjIL8=","MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE34qdEtOeD21+CmmfTmFyRr/vySsY1TD6BJZFtwF37pkelvN2vRYWWHdLrUouzkQXEfnA7V50xK2QcmnBCGsxbA==","MCowBQYDK2VwAyEAtkfghYcdvSRf2wA01gjQtgTqdYGjaDUZsOPXzgLnnT0=","MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYYmQNAMnVKK7G3VVguAk3SC/RFT5SDjCoxcFMOPFx0vmsGycJWOK8hCdxuTCHlvShng1fo0y4Q9PJHPIGQ9EfA=="],
});
const form = document.querySelector("#signup");
form.addEventListener("submit", async (event) => {
  event.preventDefault();
  try {
    // A fresh token for every attempt: single use, valid for 120 seconds.
    form.elements["blockalt-token"].value = await protection.execute("signup");
    form.submit();
  } catch {
    form.querySelector(".error").textContent = "Please try again.";
  }
});

The browser SDK reference covers fetch requests, early preparation, cancellation and errors. The console's Install tab shows this snippet with your own keys.

5Step 5: Verify on your server #

Before creating the account, send the token to BlockAlt with your secret key. Fix the hostname and action on the server; never take them from the request.

curl -sS --max-time 3 https://blockalt.click/v1/siteverify \
  -H "Authorization: Bearer $BLOCKALT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"token":"<value of blockalt-token>","hostname":"example.com","action":"signup"}'

{ "success": true, "reason": "accepted", "id": "5b0b6f0e-5d0c-4bd2-9f7e-0d3c2a1e9b77" }

Perform the action only when success is true. Copy-paste helpers for Node, Python, PHP, Go, Ruby, Java and C# are in server snippets.

6Step 6: Check it works #

• Submit the form: the console's decision log shows accepted.
• Submit the same token again, for example with your browser's network tools: the answer is already_used.
• Wait more than two minutes before verifying a token: the answer is expired_token.

Then add the CSP entries if your site uses a Content-Security-Policy, and decide what to do when BlockAlt cannot be reached.