Authentication

Every SDK call to api.tobeverified.com needs an API key in the Authorization header. Keys are scoped to a single account; tasks you submit are visible only to that account.

Sign up

Visit app.tobeverified.com. Sign in with GitHub, Google, or email magic link. Your TBV account is created on first sign-in — separate from any other product (GitProduct, Ulu, etc.) you may use under the same identity.

Create an API key

1. 1. Go to app.tobeverified.com/keys.
2. 2. Click Create. Give it a name (e.g. local-dev, prod).
3. 3. Copy the plaintext (tbv_live_…) — it's shown exactly once. Save it in your password manager or secrets store.
4. 4. Use it as your TBV_API_KEY.

Use it in the SDK

Both SDKs default to env-var lookup.

export TBV_API_KEY=tbv_live_a1b2c3...

Or pass explicitly:

from tobeverified import TBV
tbv = TBV(api_key="tbv_live_a1b2c3...")

import { TBV } from "tobeverified";
const tbv = new TBV({ apiKey: "tbv_live_a1b2c3..." });

Direct HTTP

curl https://api.tobeverified.com/v1/tasks \
  -H "Authorization: Bearer $TBV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Is this a refund request?",
    "context": {"message": "I want my money back"},
    "allowed_verdicts": ["yes", "no"],
    "confidence_threshold": 0.85
  }'

Tenancy guarantees

• Strict scoping. A task created with key A is invisible to key B unless B belongs to the same account. Cross-account requests for a task ID return 404, not 403.
• Reviewer scoping. Tasks routed to human_needed appear at review.tobeverified.com only when you're signed in to the owning account.
• Last-used tracking. Each key updates last_used_at on every successful call. Visible in your dashboard.

Rotating a key

1. 1. Create a new key in the dashboard.
2. 2. Update your secret store / env var to the new value.
3. 3. Verify your app is using the new key (e.g. ship + smoke).
4. 4. Revoke the old key in the dashboard. Revocation takes effect within seconds.

Revoking a key

Click Revoke next to the key in the dashboard. Any request made with a revoked key returns 401 Unauthorized immediately. Revoked keys remain in the audit log (with their revoked_at timestamp) but cannot authenticate.

Errors

• 401 Unauthorized — missing / invalid / revoked key.
• 429 Too Many Requests — daily task cap exceeded (per-account; raise with us if you hit it).
• 404 Not Found — task ID belongs to a different account, or doesn't exist.

Key format

Keys are tbv_live_ + 28 hex chars (37 total). The prefix is shown in the dashboard so you can identify a key without seeing the secret. Never store keys in client-side code or browser bundles.