Getting Started

Authentication

API keys, JWT sessions, scopes, 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, Principal, 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 by environment: bk_live_ in production, bk_test_ in staging. Production endpoints reject test keys and vice versa, by design.
  • Keys can be scoped on creation. The most common scopes are ledger:write, ledger:read, principal:write and certificates:read.

Creating a key

From the Ledger dashboard, open Settings → API keys → New key. Give it:

  • Name — what the key is for. We use it in audit logs.
  • Scopes — least privilege; only what the integration needs.
  • Expiry — optional but recommended. A 90-day rotation cycle is a good default.

The key's secret is shown once on the create screen. After that we only store a salted hash. If you lose it, revoke and recreate.

JWT sessions (web apps only)

The Ledger and Principal 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
  • 403 Forbidden — credentials are valid but the scope is insufficient
  • 429 Too Many Requests — per-key rate limit exceeded

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.

See also