Authentication
Every /v1 request carries a bearer API key. There is no other
credential, no session, and no signature scheme to implement.
Authorization: Bearer bce_live_<id>_<secret>
How keys are stored
Only an HMAC-SHA256 hash of your key is kept. The plaintext is returned once, at creation, and cannot be retrieved afterwards — not by you, and not by us. A lost key is replaced, never recovered.
Scopes
| Scope | Allows |
|---|---|
jobs:create | Submit crawl jobs; open and close browser sessions |
jobs:read | Read your jobs, tasks and session state |
results:read | Download rendered HTML and fetch bodies |
audit:read | Read your own API activity log |
A new key receives all four. There is no customer-facing administrative scope: account management happens in the customer portal, which uses a separate login.
Ownership
Jobs, tasks, sessions and audit records belong to the account whose key created them. A request for a resource belonging to another account returns 404, not 403 — the API will not confirm that an identifier you do not own exists.
Rotating a key
- Create the replacement in the portal and deploy it.
- Confirm traffic has moved — check
GET /v1/me/audit. - Revoke the old key.
Revocation takes effect within 60 seconds, the lifetime of the authentication cache. If a key has leaked, revoke first and accept the outage: a minute of failed requests is cheaper than a minute of someone else's.
Confirming which key you are using
import os
import requests
API = os.environ.get("API", "https://bankworks.info")
API_KEY = os.environ["API_KEY"]
response = requests.get(
f"{API}/v1/me",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
principal = response.json()["principal"]
print(principal["name"], principal["scopes"])
const API = process.env.API ?? "https://bankworks.info";
const API_KEY = process.env.API_KEY;
if (!API_KEY) throw new Error("Set API_KEY first");
const response = await fetch(`${API}/v1/me`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { principal } = await response.json();
console.log(principal.name, principal.scopes);
curl -sS -H "Authorization: Bearer $API_KEY" "$API/v1/me"
{"ok": true, "principal": {"consumerId": "…", "apiKeyId": "…",
"name": "research-team-a", "scopes": ["jobs:create","jobs:read",
"results:read","audit:read"]}}