Authentication

Every Read API request needs a Bearer token in the Authorization header.

Bearer tokens

All endpoints under api.buildonto.dev/v1/* require a Bearer token. Get yours from /read/keys in the dashboard — a default key is auto-provisioned on first visit.

bash

curl -H "Authorization: Bearer onto_sk_..." \
  https://api.buildonto.dev/v1/usage

⚠

Treat keys as secrets. Store them server-side. Anyone with the token can spend your quota and credits. We hash keys on our side (SHA-256) so we can never show you a key again after creation — copy it once on the reveal modal, store it in your secrets manager.

Get a key

Sign in at app.buildonto.dev → /read/keys. Your first key is created automatically when you land there. Click Create keyto make more (5-key limit per account). The one-time reveal modal shows the full token — you have one chance to copy it.

Key prefixes

Every key starts with a prefix that's safe to log and search for. The full token is the prefix plus a secret tail. We store only the SHA-256 hash, never the raw token.

text

onto_sk_live_3xR2pY8...
^^^^^^^^^^^^^^^^^^^^
prefix (safe to log)    secret tail

Rotation + revocation

Revoking a key takes effect immediately — any in-flight request using it gets a 401 UNAUTHORIZED on the next call. Revoked keys stay in your /read/keys list for audit (greyed out) but can't be re-activated. Create a new key, swap it in, then revoke the old one.

ℹ

Per-user vs per-site keys. The Read API uses per-user Bearer tokens (issued from /read/keys). The Serve SDK uses a separate per-site key (visible at /serve/settings) sent as x-onto-key by the SDK middleware. The two systems don't overlap — don't cross them.