Authentication
Every endpoint except GET /openapi.json requires an API key, sent as a
bearer token. The same key reads the report through
POST /graphql.
curl "https://api.beket.ai/api/v1/audits" \ -H "Authorization: Bearer bkt_your_key_here"Getting a key
Section titled “Getting a key”Keys are minted by an organization owner in Settings → Developer & AI → API keys in the dashboard. There is no endpoint that mints keys: key management is deliberately dashboard-only, so a leaked key cannot be used to mint more.
Store the key like a password. It is shown once, it carries your organization’s data access, and anyone holding it can spend your plan’s run budget.
What a key can reach
Section titled “What a key can reach”Four separate limits apply to every request, in this order:
| Limit | Failure | What it means |
|---|---|---|
| The key is valid | 401 | Missing, malformed, revoked, or expired. |
| The plan allows programmatic access | 402 | Programmatic access is a paid capability, except for the Zapier endpoints and POST /audits/{auditId}/prompts/bulk, which a free-plan key may call. On any other path a free-plan key is rejected before it reaches any handler. |
| The key’s scope permits the verb | 403 | A read-only key receives 403 on anything that is not a GET, HEAD, or OPTIONS. |
| The key’s role permits the request | 403 | A key acts with its creator’s current role, capped at editor — see below. |
Organization scoping
Section titled “Organization scoping”A key is scoped to the organization that created it, and a key never sees another organization’s data. This is enforced at the application layer on every read and every write, not left to the database.
Never more than an editor
Section titled “Never more than an editor”A key acts with the role its creator holds now, capped at editor. If the creator is later made a viewer, the key’s writes start answering 403. Owner-only surfaces — API keys, billing, members, organization settings — answer 403 to every key, which is why they are not in this reference.
Read-only and read-write
Section titled “Read-only and read-write”Choose the narrowest scope that does the job. A read-only key is the right default for anything that watches — a dashboard, a reporting job, a Looker connector, an agent answering questions about your visibility. Reserve read-write for the setup path that actually creates audits and starts runs.
Why a forbidden resource returns 404
Section titled “Why a forbidden resource returns 404”A request for a resource belonging to another organization returns 404, not 403.
This is deliberate. A 403 would confirm that the resource exists, which is itself information you should not be able to obtain about someone else’s account. The API does not confirm that a resource it will not show you exists.
The practical consequence: when you get a 404 on an id you believe is real, check which organization the key belongs to before assuming the resource was deleted.
Rate limits
Section titled “Rate limits”Limits are applied per key. The namespaces that integrations poll on a schedule carry a published limit:
| Namespace | Limit |
|---|---|
/zapier/* | 120 requests per minute per key |
/looker/* | 120 requests per minute per key |
Elsewhere the limits may change while the API is in beta, so no fixed number is published — treat
429 as a normal, expected response and back off when you see one, rather than tuning to a
specific rate.
See Errors for what to do with a 429.
The one public endpoint
Section titled “The one public endpoint”GET /openapi.json takes no credentials at all. It exists so a developer —
or an agent — can read what the API offers before holding a key. It is the only operation whose
security is empty, and consequently the only one that never answers 401, 402, or 403.