Authentication

Botect uses three credentials: an account API token for configuration, a site key for ingest, and a private key for verdict reads.

Botect separates its control plane (configure scoring) from its data plane (send signals, read verdicts), and each uses a different credential. Picking the right one per call matters: site keys are public by design, private keys must never leave your servers.

The three credentials

Credential	Prefix	Used for	Sent as	Secrecy
Account API token	—	Control plane: enable scoring, settings, rules	`Authorization: Bearer <token>`	Secret (server-side)
Site key	`pk_`	Data plane: ingest events from the browser	`X-Botect-Site-Key: pk_…`	Public (ships in the browser)
Private key	`sk_`	Data plane: read session verdicts	`Authorization: Bearer sk_…`	Secret (server-side)

The site key and private key are minted together when you enable scoring on a project. The account API token is created in the dashboard.

Account API token

Used for every control-plane endpoint under /v1/projects/{project}/… — and for /user and /account. It is scoped to your account; the project must belong to it.

Open the dashboard

Create a token

Give it a descriptive name (e.g. ci, provisioning) and submit.

Copy it immediately

The full secret is shown once. Store it in a secrets manager.

curl https://api.botect.ai/v1/account \
  -H "Authorization: Bearer YOUR_ACCOUNT_TOKEN"

Token abilities

When you create a token you choose its abilities — either Full access (a wildcard that grants everything your role permits) or a custom subset. Most control-plane endpoints are satisfied by any valid token, but some require a specific ability:

Ability	Grants
`projects:read`	Read project configuration and reference data — e.g. export verified bots
`projects:write`	Create and update project scoring configuration
`content:read` / `content:write`	Read / write content-tier resources

Two bounds apply at request time: the token's stored abilities are the lower bound, and your current role on the account is the upper bound. A wildcard token only ever grants what your role still allows — so if your role is reduced, the token's reach narrows with it. A call that needs an ability the token lacks returns 403 INSUFFICIENT_TOKEN_ABILITY.

Site key

A public, project-scoped key prefixed pk_. It authenticates POST /v1/events — the ingest calls your browser SDK makes. Because it ships to the browser, it is not a secret: it can only add signals, never read verdicts or change configuration.

X-Botect-Site-Key: pk_YOUR_SITE_KEY

The site key may also be sent as a site_key field in the request body. The header is preferred.

Private key

A secret, project-scoped key prefixed sk_. It authenticates GET /v1/sessions/{token}/verdict — the verdict reads your backend makes. Botect stores only a SHA-256 hash of it, so it cannot be recovered after issuance — only rotated.

Authorization: Bearer sk_YOUR_PRIVATE_KEY

It may also be sent as X-Botect-Private-Key. Either works:

X-Botect-Private-Key: sk_YOUR_PRIVATE_KEY

Never put a private key or account token in client-side code. Only the site key belongs in the browser. Verdict reads and configuration must happen from your backend.

Rotating keys

The site and private keys can be rotated independently — for example after a suspected leak. Rotation issues a new key and immediately invalidates the old one.

curl -X POST https://api.botect.ai/v1/projects/123/scoring/rotate \
  -H "Authorization: Bearer YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "private" }'

See Rotate a key for details. Account API tokens are rotated by deleting and recreating them in the dashboard.

Common authentication errors

Status	`code`	Meaning
`401`	`UNAUTHENTICATED`	Missing, malformed, or revoked credential — or a site/private key for a project without scoring enabled
`402`	`NO_ACTIVE_SUBSCRIPTION`	The credential is valid but the owning account has no active subscription
`403`	`INSUFFICIENT_TOKEN_ABILITY`	The token lacks an ability the endpoint requires (e.g. `projects:read`)

See Errors for the full reference.

Was this page helpful?