API authentication

Every call that is not anonymous carries an API key.

curl https://scribiz.com/api/v1/me \  -H "Authorization: Bearer $SCRIBIZ_API_KEY"

You can send the key in an X-API-Key header instead. Use one or the other. A key in a URL, such as ?key=..., is ignored, and the call is then anonymous.

What a key looks like

sbz_live_ followed by random characters. The prefix lets secret scanners, such as GitHub's and gitleaks, find a key that was committed by mistake.

Keys are created in the dashboard, under API keys, after you sign in with an email link. Copy the key when it appears. It is shown once. Scribiz keeps only a hash of it, so a lost key cannot be shown again.

Creating and revoking a key needs a signed-in session, which the dashboard has. A key cannot do either, even one with the all scope. POST /v1/keys and DELETE /v1/keys/:id with a key answer 403 with session_required. GET /v1/keys works with an all key.

{  "keys": [    {      "id": "key_GDAeFMIBQ2lh",      "name": "CI",      "prefix": "sbz_live_",      "last4": "rz97",      "scopes": "all",      "createdVia": "dashboard",      "deviceLabel": null,      "createdAt": 1791093414824,      "lastUsedAt": 1791093428666,      "expiresAt": null    }  ]}

A key made through command-line sign-in (scribiz login, from version 0.1.1 of the CLI) has createdVia: "cli" and the name of the machine in deviceLabel, and is named CLI on and that machine. It has the scope all. Revoke it like any other key.

Scopes

Give a key the smallest scope that works. A key for an agent needs only mcp. A dashboard that shows results needs only read. Creating or deleting a job needs all. A read key that tries answers 403 with insufficient_scope.

An account can have up to 10 active keys. Another one is 409 with key_limit_reached. The dashboard lists when each key was last used.

Rotate a key

1. Create a new key.
2. Deploy it to the place that uses the old one.
3. Check that the old key's last-used time stops moving.
4. Revoke the old key.

A revoked key stops working at once on the server that revoked it, and within about a minute everywhere.

Rules

• Keep keys on a server. Calls with an API key are not meant to come from a browser. The API answers cross-origin browser requests only for Scribiz's own site, so a page on another origin cannot use a key. This is deliberate: a key in a web page is not a secret. Call your own server from the page, and call Scribiz from there.
• Do not put keys in URLs. Keys are only accepted in headers.
• One key per service. Then you can revoke one without breaking the rest.
• One balance. A key draws on the minutes of the account that made it. MCP and the API share that balance.

Anonymous requests

The web tool works without a key for captions and a small daily quota of Listen and Watch. Those calls come from a browser. When the server has Cloudflare Turnstile on, a Listen or Watch request needs a turnstile_token. Do not build on anonymous access. It is limited by connection, it is rate limited, and Listen and Watch can be switched off when demand is high. Use a key.

Browser sessions

The Scribiz website uses a cookie session for the signed-in pages. A session is not an API credential. Code uses an API key. Signing in from the command line (scribiz login) ends with a key too: the CLI swaps the browser approval for an API key and the session ends. See Sign in from the CLI.

Errors

{ "error": { "code": "invalid_api_key", "message": "This API key is not valid. It may have been revoked or expired." } }

See Errors and limits.