API keys and authentication
The API reference lists every endpoint with its request and response schema, rendered from the OpenAPI document; this page explains how the calls behave.
Authentication
Machine endpoints use a Bearer token. Send it on every request.
Authorization: Bearer YOUR_TOKEN
Your token authenticates your calls to us. It does not sign anything we send you: the finalize callback and webhooks each have their own signing secret (see Finalize callback and Webhooks). The browser panel can also call these endpoints from a logged-in session, so the in-app LQA tab works without a token.
Scopes
A workspace API key carries scopes, and a call needs the one that covers it. A workspace admin creates keys in Settings, Developer, picks the scopes and can set a date the key stops working. API keys are available on Team and above. A key looks like snah_.... The full key is shown once when it is created and never again, so copy it then. The same tab lists the workspace's keys, and revoking a key there stops it at once. A call that needs a scope the key does not hold is a 403.
| Scope | Opens |
|---|---|
qa:write | Submit a QA check, run a file into a report or a version compare. Mark findings fixed or ignored, and make or revoke a report's share link. |
qa:read | Poll a check, read a change report, list runs, read a report and download its files, read the profiles, one profile's settings and the month's usage. |
qa:delete | Delete a report for good. Never ticked by default: a workspace admin adds it to a key on purpose. |
lqa:write | Create, score, assign, finalize and re-open LQA jobs. Also save and delete templates. |
lqa:read | Read LQA jobs and the job list, the live scores, the templates, the analytics and the calibration. |
eval:write | Create an engine comparison. In generate mode this spends real MT and LLM money, which is why it is its own scope. |
eval:read | Read eval runs, the scoreboard, the side-by-side comparison, the engine and model catalog, the metric registry and the analytics. |
webhooks:manage | Register, edit and delete outbound webhooks. |
A write scope does not include the read. The two are independent: a key holding only qa:write can submit a check and gets 403 when it polls the result. An integration that submits and then reads needs both scopes on the key. The same applies to the LQA and Eval pairs.
Base URL and a personal token
The base URL is https://app.stillneedsahuman.com.
A personal token. Sign in and open User settings from your avatar menu. Under Browser extension, click Connect this browser to mint a personal token. It is tied to your account and your workspace, so every call is automatically scoped to your own data only. Revoke it any time from the same screen or by changing your password.
The legacy token
One shared adapter token from before workspace keys is still accepted on the QA adapter, for the integrations built on it. It maps to the platform's default workspace with every scope but qa:delete. New integrations use a workspace snah_ key: on the QA adapter each endpoint checks the key's scopes, and the LQA calls need a valid key bound to your workspace.
Workspaces
Every account belongs to a workspace. The API is automatically scoped: a token only ever sees and writes its own workspace's profiles, reports, LQA jobs and Eval runs. There is nothing extra to send; the same QA, LQA and Eval endpoints above work unchanged for every workspace.
| Concept | What it means for the API |
|---|---|
| Token = workspace | Your Bearer token determines the workspace; calls never cross into another. |
| Modules | A workspace is enabled for some of QA, LQA and Eval. A write to a module it does not have returns 403. QA reads are the exception and stay open: a report shared into your workspace has to remain readable whatever your workspace bought. LQA and Eval reads do require their module. |
| Plan | A workspace on a live plan may read and write. On a view-only plan, or once a trial has ended, it may still read everything it could before and every write returns 403. A suspended workspace is refused everything. Reads included, and its keys stop working. |
| Limits | Rate limits and the AI ceiling are per workspace. See Rates and ceilings. |
| Onboarding | A workspace admin invites users from Settings › Members; each user mints their own token. |