Bankworks

Authentication

Every /v1 request carries a bearer API key. There is no other credential, no session, and no signature scheme to implement.

HTTP
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

ScopeAllows
jobs:createSubmit crawl jobs; open and close browser sessions
jobs:readRead your jobs, tasks and session state
results:readDownload rendered HTML and fetch bodies
audit:readRead 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

  1. Create the replacement in the portal and deploy it.
  2. Confirm traffic has moved — check GET /v1/me/audit.
  3. 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

GET /v1/me
Python
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"])
Node.js
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
curl -sS -H "Authorization: Bearer $API_KEY" "$API/v1/me"
JSON
{"ok": true, "principal": {"consumerId": "…", "apiKeyId": "…",
 "name": "research-team-a", "scopes": ["jobs:create","jobs:read",
 "results:read","audit:read"]}}