Management API · Docs

API keys #

Owners and admins create management API keys in the console (API keys). A key belongs to one workspace, is shown once, is stored only as a hash and expires after 7, 30, 90 or 365 days, or never. Revoke it at any time; requests with a revoked or expired key get 401 invalid_api_key. Creating and revoking keys needs a fresh second factor, and workspace owners get an email each time.

A key never outlives its creator's rights: it works only while the person who created it is an owner or admin of the workspace. Removing that person, making them a member, their leaving the workspace or deleting their account revokes the keys they created; give automation that must survive staff changes a key created by a long-term admin, and rotate it when people leave.

Scopes #

Scope	Allows
`read`	Sites, their settings, health, decision log, refusals, analytics and usage, their CSV exports, and the workspace name
`sites:write`	Create sites, save drafts, publish settings, verify domains, rename sites and set their alert rules
`keys:write`	Create, revoke and name site server keys
`billing:read`	Wallet, ledger, orders, receipts, statements and billing CSV exports

Pausing, locking down or resuming protection (also publishing a version that pauses or locks down), deleting sites, top-ups and the warning threshold, notification destinations, members, invitations, ownership, the audit log, API keys, the export and deletion are console-only: they concern people, money, secrets or switching protection off. A key gets 403 session_required for them, and 403 scope_required for a route whose scope it lacks. A console route added later stays console-only until it is listed here. A key with keys:write creates and revokes server keys without a fresh second factor (the key is the credential for that automation); the same changes from a console session ask for one.

Route	What it does	API key
`GET /v1/console/sites`	List sites with their setup health	`read`
`POST /v1/console/sites`	Create a site (returns its first secret key)	`sites:write`
`GET /v1/console/sites/{id}`	A site with keys, hostnames and versions	`read`
`POST /v1/console/sites/{id}/draft`	Save a settings draft	`sites:write`
`POST /v1/console/sites/{id}/publish`	Publish a settings version	`sites:write`
`POST /v1/console/sites/{id}/state`	Resume, pause or lock down protection	Console only
`POST /v1/console/sites/{id}/verify-domain`	Check a hostname's DNS TXT record	`sites:write`
`POST /v1/console/sites/{id}/keys`	Create a server key (shown once)	`keys:write`
`POST /v1/console/sites/{id}/revoke-key`	Revoke a server key	`keys:write`
`POST /v1/console/sites/{id}/key-label`	Name a server key	`keys:write`
`POST /v1/console/sites/{id}/rename`	Rename a site	`sites:write`
`POST /v1/console/sites/{id}/delete`	Delete a site	Console only
`POST /v1/console/sites/{id}/alerts`	Set the site's alert rules	`sites:write`
`GET /v1/console/sites/{id}/live`	Installation check: recent verifications	`read`
`GET /v1/console/sites/{id}/events`	Decision log (seven days)	`read`
`GET /v1/console/sites/{id}/refusals`	Refusals counted per minute (seven days): browser side, or phase=verification	`read`
`GET /v1/console/sites/{id}/analytics`	Daily decision counts	`read`
`GET /v1/console/sites/{id}/events.csv`	Decision log as CSV	`read`
`GET /v1/console/sites/{id}/analytics.csv`	Daily decision counts as CSV	`read`
`GET /v1/console/sites/{id}/usage`	Accepted verifications per day	`read`
`GET /v1/console/sites/{id}/ledger`	Ledger rows of one site (legacy)	`billing:read`
`POST /v1/console/sites/{id}/topups`	Top up from a site page (legacy)	Console only
`GET /v1/console/billing`	Wallet, plan, usage and forecast	`billing:read`
`GET /v1/console/billing/status`	Billing state for banners and badges	`billing:read`
`GET /v1/console/billing/ledger`	Credit ledger	`billing:read`
`GET /v1/console/billing/orders`	Top-up orders	`billing:read`
`GET /v1/console/billing/orders/{id}`	A top-up receipt	`billing:read`
`GET /v1/console/billing/statements`	Months with a statement	`billing:read`
`GET /v1/console/billing/statement`	A month's statement	`billing:read`
`GET /v1/console/billing/export`	Ledger or usage as CSV	`billing:read`
`POST /v1/console/billing/topups`	Start a top-up (WayCash checkout)	Console only
`POST /v1/console/billing/threshold`	Set the low-balance warning	Console only
`GET /v1/console/workspace`	The workspace's name and your role	`read`
`POST /v1/console/workspace`	Rename the workspace	Console only
`GET /v1/console/members`	List members	Console only
`GET /v1/console/invitations`	List pending invitations	Console only
`POST /v1/console/invitations`	Invite someone	Console only
`POST /v1/console/invitations/revoke`	Revoke an invitation	Console only
`POST /v1/console/accept-invitation`	Accept an invitation	Console only
`POST /v1/console/members/remove`	Remove a member	Console only
`POST /v1/console/members/role`	Change a member's role	Console only
`POST /v1/console/leave`	Leave the workspace	Console only
`POST /v1/console/transfer-ownership`	Transfer ownership to an admin	Console only
`GET /v1/console/audit`	Audit log	Console only
`GET /v1/console/audit/actors`	People and keys in the audit log	Console only
`GET /v1/console/export`	Export the workspace as JSON	Console only
`POST /v1/console/workspace/delete`	Ask to delete the workspace (emails a link)	Console only
`GET /v1/console/api-keys`	List management API keys	Console only
`POST /v1/console/api-keys`	Create a management API key (shown once)	Console only
`POST /v1/console/api-keys/revoke`	Revoke a management API key	Console only
`GET /v1/console/notifications`	Notification destinations and delivery	Console only
`POST /v1/console/notifications`	Add a notification destination (webhook secret shown once)	Console only
`POST /v1/console/notifications/{id}/toggle`	Enable or disable a destination	Console only
`POST /v1/console/notifications/{id}/delete`	Delete a destination	Console only
`POST /v1/console/notifications/test`	Send a test notification	Console only

Requests #

Send the key as a bearer token. No cookie, Origin header or CSRF token is involved, and the key's workspace is used (an X-Workspace-Id header, if sent, must match it).

Shell

curl -sS https://blockalt.click/v1/console/sites \
  -H "Authorization: Bearer $BLOCKALT_API_KEY"

Shell

# Rotate a site's server key from CI (scope keys:write)
curl -sS -X POST https://blockalt.click/v1/console/sites/$SITE_ID/keys \
  -H "Authorization: Bearer $BLOCKALT_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

Every route, with its request schema, is in the OpenAPI document under the managementKey security scheme. Changes made with a key appear in the audit log under the key's name.

Limits #

Each key can make about 10 requests a second (bursts of 600); writes also count toward the workspace's limits. Over the limit, the answer is 429 rate_limited with Retry-After.