Skip to main content

API keys

Every call to the partner API carries an API key as a bearer token:

Authorization: Bearer bk_live_…

Create a key​

Keys are created in the Before Partner Portal. Pick the funeral home, the user who will sell with it, the mode and the origins of the pages that open the wizard. The key is shown once, when it is created; store it on your server and never in a browser. Access to the portal comes with onboarding: email hello@before.com to get started.

One key per user​

Each key belongs to one user at one funeral home, in one mode. The key names who sells: every sale opened with it is attributed to that user, who becomes the producer of record and receives the commission for the policy. A session request never names the user; the key does.

A funeral home with several selling users gets one key for each of them, and you pick the key by the user signed in to your platform. A key sees only its own funeral home's sales, and only those its user may see.

If a user leaves the funeral home or loses the right to sell, their key stops opening sessions and reading sales with 409 key-user-inactive. Revoke it and create a key for whoever sells now.

Live and test​

PrefixModeSales it opens
bk_live_liveReal sales, sent to the carrier.
bk_test_testPractice sales, never sent to a carrier. See Sandbox.

Each user has at most one active key per mode. Each key reads only the sales opened in its own mode: a test key gets 404 for a live sale.

Shown once​

Before stores only a hash of the key and keeps its last four characters. Nobody, Before included, can show the full value again. If you lose a key, revoke it in the Partner Portal and create another.

Keep keys on your server, in a secret store. Never send one to a browser, embed it in a mobile app or log it. The browser only ever sees the short-lived session_token.

What a key can call​

A key can call exactly two routes:

  • POST /v1/partner/sessions
  • GET /v1/partner/sales/:id

Anything else answers 403. A missing, unknown or revoked key answers 401.

Embed origins​

Each key lists the origins of the pages that open the wizard, such as https://crm.example.com: HTTPS, no path, up to ten. The wizard posts its before:complete and before:exit messages only to these origins, so a page whose origin is missing never hears them. Edit the list in the Partner Portal; the change applies to new sessions.

Framing the wizard also needs your origin on Before's framing allowlist; see Embed script.

Rotating a key​

Because a user has one active key per mode, rotation is revoke, then create, in the Partner Portal:

  1. Revoke the old key. Requests with it fail with 401 at once, and wizards it opened close with onExit reason expired.
  2. Create a new key for the same user with the same embed origins.
  3. Deploy the new key.

Requests between steps 1 and 3 fail, so keep the gap short. If a key may have leaked, revoke it at once.

Rate limits​

Before rate limits each key. Past the limit a request answers 429; wait a few seconds and retry, with backoff.