Authentication and API keys

Every request to the API, except GET /plans and GET /languages, carries an API key in the Authorization header.

Authorization: Bearer swp_0190EXAMPLE_EXAMPLEEXAMPLEEXAMPLE

The Bearer scheme is case-insensitive. The whole header can be at most 256 bytes.

Create a key

Keys are created and revoked in the app, under Settings → API. Creating a key needs the Unlimited plan.

1. Open Settings → API and choose to create a key.
2. Give it a name of 1 to 60 characters, with no control characters. Use a name that tells you where the key lives, such as production-worker.
3. Copy the key when it is shown.

The key is shown once

The full key appears only at creation. Scribewren stores a SHA-256 hash of it and the last four characters, so it cannot show the key again. If you lose a key, revoke it and create a new one.

You can have up to 10 active keys per account. Use one key per service or environment, so you can revoke one without touching the others. The key list shows each key’s name, last four characters, creation time and last use. The last-use time updates at most every 5 minutes.

A key cannot create, list or revoke keys, and it cannot manage webhook endpoints. Those actions need a signed-in session in the app.

Key format

A key starts with swp_, followed by the key’s ID and a random secret. Treat the whole string as opaque: do not parse it, and do not rely on its length.

Keep keys safe

• Keep keys on your server or in a secret manager, and pass them to your code through an environment variable. The examples in these docs read SCRIBEWREN_API_KEY.
• Never put a key in a URL or query string. URLs end up in logs, browser history and proxies. The API only accepts the Authorization header.
• Never put a key in browser JavaScript, a mobile app or a public repository. The API host sends no CORS headers, so browsers cannot call it anyway.
• Rotate a key by creating a new one, deploying it, and then revoking the old one.
• Revoking takes effect on the next request. A revoked key returns 401 UNAUTHENTICATED.

What a key can do

A key acts as its owner, on the endpoints listed in the API overview. There are no scopes: any key can use any of those endpoints. Resources are private to the account, so a key can never read another account’s data. A request for someone else’s resource returns 404 NOT_FOUND.

API calls count against the same plan limits and fair use as the app. See Usage to read your own counters.

Authentication errors

A request with a missing, malformed, unknown or revoked key always gets the same answer, so a response does not reveal whether a key ever existed.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "code": 401,
  "message": "Authentication required.",
  "data": null,
  "error": { "code": "UNAUTHENTICATED", "details": {} },
  "meta": {
    "requestId": "019a4f30-1c22-7a10-b5d3-42f1c0a8e777",
    "timestamp": "2026-12-01T09:41:07.512Z"
  }
}

Status	error.code	Meaning
401	UNAUTHENTICATED	The key is missing, malformed, unknown or revoked. The response has WWW-Authenticate: Bearer.
403	FEATURE_NOT_IN_PLAN	The key’s owner is not on Unlimited. details is { "feature": "api", "requiredPlan": "unlimited" }.
403	ACCOUNT_SUSPENDED	The owner’s account is banned (details.reason is banned) or is being deleted (details.reason is deletion_pending).
429	RATE_LIMITED	Too many requests from the key, the account or the IP address. See Rate limits.
503	SERVICE_UNAVAILABLE	The key could not be checked right now. Retry with backoff.

Plan changes

The API checks the owner’s plan and account status on every request, not only when the key is created.

• If the account leaves Unlimited, calls return 403 FEATURE_NOT_IN_PLAN. The keys are kept, and they work again as soon as the account is on Unlimited. You can still list and revoke keys in the app on any plan.
• If the account is deleted, all its keys are revoked.
• On a restricted account, reads, exports and deletes still work, but anything that starts new processing (creating media, completing an upload, retrying a job) returns 403 ACCOUNT_RESTRICTED.

See Plans and billing for how plans and downgrades work.