Installation

Script tag #

Load the content-addressed script with its Subresource Integrity hash. The file at that address never changes, so a pinned page keeps working across our releases.

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

The current release is 0.3.0 at /v1/assets/blockalt.c8b2d9539dbbc932999adb0f51a36bddd4e99899f543e1505818841878cf9813.js, 4,640 bytes gzip. The console shows the same values on your site's Install tab, already filled in with your site key and every key to pin, and the manifest publishes them as JSON:

curl -sS https://blockalt.click/v1/script-manifest

{
  "version": "0.3.0",
  "path": "/v1/assets/blockalt.c8b2d9539dbbc932999adb0f51a36bddd4e99899f543e1505818841878cf9813.js",
  "bytes": 10099,
  "gzipBytes": 4640,
  "gzipBudgetBytes": 5120,
  "integrity": "sha384-pblByFDqcJxRfhDh18GH3gRsWy9ZaS4AjDc6OpozzQqvkuYvyin+4BWcKXxA+bN8"
}

/v1/blockalt.js always serves the newest script and is cached for five minutes; it cannot be pinned with SRI, so use it only where you accept automatic updates.

Create the client #

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=="],
});

Configuration keys #

The script trusts a site configuration only when it is signed by one of the keys you pinned. Copy them from the console, or read them from the API:

curl -sS https://blockalt.click/v1/keys
# {
#   "configPublicKeys": ["MCowBQYDK2VwAyEA…", "MFkwEwYHKoZIzj0CAQYI…", "…"],
#   "current": { "ed25519": "MCowBQYDK2VwAyEA…", "p256": "MFkwEwYHKoZIzj0CAQYI…" },
#   "standby": ["…"]
# }

Pin every key in configPublicKeys: the current Ed25519 and P-256 keys and the standby keys. The standby keys let us rotate the signing key without breaking your page; see key rotation.

The keys to pin today, as GET /v1/keys lists them (every snippet in these docs already contains them):

[
  "MCowBQYDK2VwAyEAXmYdcBh/jf+z+0H+hs2QvZ9UG4PBgkRvHX/JuXyjIL8=",
  "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE34qdEtOeD21+CmmfTmFyRr/vySsY1TD6BJZFtwF37pkelvN2vRYWWHdLrUouzkQXEfnA7V50xK2QcmnBCGsxbA==",
  "MCowBQYDK2VwAyEAtkfghYcdvSRf2wA01gjQtgTqdYGjaDUZsOPXzgLnnT0=",
  "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYYmQNAMnVKK7G3VVguAk3SC/RFT5SDjCoxcFMOPFx0vmsGycJWOK8hCdxuTCHlvShng1fo0y4Q9PJHPIGQ9EfA=="
]

Hostnames and origins #

• Each origin listed for the site is exact: scheme, host and port, no path. Up to 20 origins per site.
• Each hostname needs the TXT record _blockalt.<hostname> with the value from the console. Routing does not change. When a check fails, the console says what it found: no record, other values, a timeout or a DNS server error.
• A wildcard origin such as https://*.example.com covers exactly one level of subdomains on HTTPS and the same port: https://pr-12.example.com, but neither https://example.com (list it separately) nor https://a.b.example.com. It is verified by the TXT record of its base, _blockalt.example.com, so only someone who controls that DNS zone can use it, and a public suffix such as *.co.uk or *.vercel.app can never be verified.
• The page's hostname is written into every token, including under a wildcard; your server sends the hostname it expects, in lower case and without a port. Analytics count wildcard pages under the wildcard (*.example.com).

Next #

• Your page has a Content-Security-Policy? Add the CSP entries.
• Using a framework? Pick a framework guide.