Authentication and errors
Write keys, rotation, and every error code.
Write keys
Send results and rotate keys with your project's write key in a bearer header: Authorization: Bearer bdg_wk_.... The bdg_wk_ prefix lets secret scanners find leaked keys.
- We show a key once, when you create the project or rotate it.
- We store only a SHA-256 hash, so we cannot recover a lost key.
POST /v1/keys/rotateissues a new key and revokes the one you used immediately. You can also rotate from the project page in the dashboard.- The
badge_idis public and is not a credential.
Dashboard sign-in
The dashboard uses a one-time email link or Google sign-in. A project you created through the API appears once you sign in with the same, verified email address.
Errors
Every error has the same shape, and the HTTP status tells you the class of problem:
{ "error": { "code": "invalid_request", "message": "total: passed + failed must not exceed total" } }Branch on the code, not the message. Messages are for people and may change.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The body is not valid JSON or fails validation. The message names the field. |
| 401 | invalid_key | The write key is missing, malformed, unknown or already rotated. |
| 403 | forbidden | A dashboard form post did not come from our own site. |
| 404 | not_found | No such route. |
| 404 | unknown_api_version | The path starts with a version we do not have, such as /v9. |
| 413 | payload_too_large | The body is larger than 1 KB. |
| 429 | rate_limited | Too many requests from this address or for this key. See Retry-After. |
| 429 | monthly_limit_exceeded | The project used its monthly results on the Free plan. |
| 429 | daily_cap_reached | We paused ingest for the day across the service. |
| 429 | too_many_projects | This email already has the maximum number of projects. |
| 500 | internal_error | Something went wrong on our side. Retrying with the same run_id is safe. |
| 501 | not_implemented | The endpoint exists but is not enabled. |
| 503 | database_unavailable | Our health check could not reach the database. |
Every response includes an X-Request-Id header. Quote it if you contact us.