Becoming You Labs Partner API

Public partner API for administering Becoming You Labs assessments to your end users. The first available product is the Values Bridge (values-bridge). Routes are product-scoped (/v1/{product}/...) so additional assessment products can be added without breaking changes.

Authentication

All /v1 requests are authenticated at the API gateway with an API key. The gateway forwards the resolved partner identity to the origin. From a partner's perspective, send your API key as documented in the developer portal; the gateway handles the rest.

Rate limits

The gateway allows 120 requests per minute per API key. Over that, it answers 429 before the request reaches the API, so a 429 body is the gateway's own, not the error envelope described below. Back off and retry.

Errors

Errors carry { "error": { "code", "message" } } and partners should branch on error.code. Validation failures are 422 invalid_request (not 400), and a suspended account is 403 forbidden.

Integration models

• Headless — create a session, render the returned question schema in your own UI, submit answers, and complete to receive results.

• Hosted — create a session with mode: "hosted" and a redirectUrl; redirect your end user to the returned hostedUrl. We host the questionnaire and redirect back to you on completion. Results are also delivered via webhook.

Webhooks

If you configure a webhook URL and secret for your account, we POST a signed JSON event to your endpoint when an assessment completes (both headless and hosted flows emit the same assessment.completed event).

Each request includes these headers:

• x-byl-event — the event type (e.g. assessment.completed).

• x-byl-event-id — a unique id for the event. Retries reuse the same id, so treat delivery as at-least-once and dedupe on this id.

• x-byl-signature — sha256=<hex>, an HMAC-SHA256 of the raw request body keyed with your webhook secret.

Verify every request before trusting it: recompute the HMAC over the raw body with your secret and compare (constant-time) against the hex in x-byl-signature. Reject on mismatch.

expected = "sha256=" + hex(hmac_sha256(secret, raw_request_body)) valid = constant_time_equals(expected, header["x-byl-signature"])

Respond 2xx to acknowledge. Non-2xx responses and network errors are retried up to 3 times with a short backoff; persistent failures are dropped (webhooks are best-effort — always reconcile with the results endpoints).