Getting Started

Authentication

API keys, JWT sessions, and rotation — everything you need to authenticate against Bedrock.

Bedrock supports two authentication paths because it serves two kinds of caller: machines and people. Programmatic clients (your back-office systems, batch jobs, webhooks) authenticate with API keys. The web apps — Ledger, Review, the customer Verify page — use a Cognito-issued JWT scoped to a session.

API keys

Pass your key in the X-Bedrock-Key header on every request:

http

GET /v1/firm/me HTTP/1.1
Host: api.bedrockcompliance.co.uk
X-Bedrock-Key: bk_live_RxYz...

Some properties to remember:

Keys are firm-scoped — they cannot be used to read another firm's data.
Keys are revocable. Revocation is immediate.
Keys are prefixed with bk_live_ (production) or bk_test_ (sandbox), followed by 64 hex characters of entropy.
Authorisation is binary today: a valid key has full access to its firm's API surface. Per-key scopes (least-privilege) are on the roadmap.

Creating a key

From the Ledger dashboard, open Settings → API keys → New key. Give it a descriptive name — that's the only field on the create form, and we surface it in audit logs and on the keys list so you can identify which integration is making which calls.

The key's secret is shown once on the create screen. After that we only store a sha256 hash plus the last four characters for identification. If you lose the secret, revoke the key and create a new one.

JWT sessions (web apps only)

The Ledger and Review apps authenticate users through Cognito. Sign-in flows produce a short-lived ID token, which the apps refresh in the background and forward to the API as a Bearer token. You don't need to think about this unless you're embedding parts of the Bedrock UI in your own portal.

For SSO and SCIM provisioning, see your firm's Settings → Single sign-on page in the Ledger dashboard.

Errors

401 Unauthorized — missing or invalid credentials. Specific codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_REVOKED, TOKEN_INVALID.
403 Forbidden — credentials are valid but the firm's plan or the user's role prohibits the operation. Specific codes: PLAN_INSUFFICIENT, VULNERABILITY_SPECIALIST_REQUIRED, SENIOR_SIGN_OFF_REQUIRED.
429 Too Many Requests — per-key rate limit. Honour the Retry-After header.

Match on the error field of the response envelope, not the HTTP status — the same status code can mean several different things. See Error codes for the full list.

Rotation

Best practice is to rotate keys quarterly, after any team change with access, and immediately after any suspected exposure. Bedrock supports overlap rotation: create the new key, deploy it everywhere, then revoke the old one. Both keys remain valid in the meantime.