Getting Started

Authentication

API keys, JWT sessions, scopes, and rotation, everything you need to authenticate against the API.

The platform 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 app and the customer Verify page use a Cognito-issued JWT scoped to a session. Third-party products that act on behalf of many firms use a connected-app grant, a variant of the machine path covered below.

API keys

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

http

GET /v1/firm/me HTTP/1.1
Host: api.bedrockgovernance.com
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.
Keys carry scopes. A standard key has full access to its firm's API surface; a scoped key is restricted to specific operations, for example generations:write, which can append generations but cannot read the ledger or manage firm settings.

Creating a key

From the dashboard, open Settings → API keys → New key. Give it a descriptive name, the only field on the create form. The name is surfaced 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, only a sha256 hash plus the last four characters is stored, for identification. If you lose the secret, revoke the key and create a new one.

JWT sessions (web apps only)

The web app authenticates users through Cognito. Sign-in flows produce a short-lived ID token, which the app refreshes in the background and forwards to the API as a Bearer token. You do not need to think about this unless you are embedding parts of the platform UI in your own portal.

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

Connected apps

A product that acts on behalf of many firms, such as a paraplanning tool that attests the advice it generates, does not hold each firm's API key. It registers once as a connected app, and each firm authorises it individually through an OAuth-style grant.

Register your product to receive a client_id and client_secret.
Send the firm to the platform's authorisation screen, requesting the scopes you need (e.g. generations:write). A firm admin approves the connection.
Exchange the returned authorisation code for a per-firm refresh token, then short-lived access tokens as needed.

Each credential is scoped and bound to one firm, and the firm can revoke your app at any time without affecting other credentials. See Build a generation integration.

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. The platform supports overlap rotation: create the new key, deploy it everywhere, then revoke the old one. Both keys remain valid in the meantime.