Authentication

Every Scriptivox API request is authenticated with an API key. There is no session login, no OAuth flow, and no cookie — a key is the only credential the API accepts.

Base URL: https://api.scriptivox.com/v1

Get a key

Create one at platform.scriptivox.com/keys. Keys look like sk_live_ followed by 48 hexadecimal characters.

The full key value is shown once, at creation. Store it immediately — the dashboard keeps only a prefix afterwards so you can tell your keys apart, and there is no way to recover a lost key. Create a replacement and revoke the old one instead.

An API key is not a web subscription

Scriptivox is two products, billed separately. A subscription on scriptivox.com grants nothing to the API, and API usage draws down a prepaid balance you top up at /billing — $0.20 per hour of audio. Even on Pro, POST /v1/transcribe returns 402 ZERO_BALANCE at $0.

Send the key

Two headers are accepted. They are equivalent — pick one:

http

Authorization: sk_live_a1b2c3...

http

X-Api-Key: sk_live_a1b2c3...

A Bearer prefix on Authorization is accepted but not required, so Authorization: Bearer sk_live_… works too. Header names are case-insensitive.

bash

curl https://api.scriptivox.com/v1/balance \
  -H "Authorization: sk_live_YOUR_KEY"

If both headers are present, X-Api-Key wins.

Limits on keys

Each account may hold at most 5 active keys. If you hit the ceiling, revoke an unused key before creating another.

Rate limits are enforced per key per endpoint, plus a per-IP cap across all endpoints. Every response — including the 401 you get with no key at all — carries RateLimit-Policy, so you can read the limits before you have a working key. See Rate Limits.

Rotating a key

Keys have no expiry, so rotation is something you choose to do rather than something forced on you:

Create the new key at /keys.
Deploy it. Both keys are live and both draw on the same account balance, so there is no cutover window to coordinate.
Revoke the old key.

Revocation takes effect immediately. The gateway caches malformed keys for five minutes to blunt brute-force attempts, but a well-formed sk_live_ key that starts returning 401 is never cached — a transient backend blip must not brick a real customer's key for five minutes, so every request re-checks. The cost of that choice is one extra lookup per failure; the benefit is that revoking a leaked key is instant.

When authentication fails

Status	Code	What happened
`401`	`INVALID_API_KEY`	No key, a malformed key, or a key that does not exist.
`401`	`API_KEY_REVOKED`	The key was valid and has since been revoked.
`402`	`ZERO_BALANCE`	The key is fine. The account balance is $0 — add credit at /billing.
`429`	`RATE_LIMIT_EXCEEDED`	Valid key, too many requests. Honour `Retry-After`.

Repeated authentication failures from one IP earn a progressive block — 60 seconds, then 5 minutes, then 30 minutes. The block returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header rather than another 401, so a client retrying a bad key in a tight loop will start seeing 429s. Fix the key rather than retrying.

Every error body is the same shape, with a stable machine-readable code:

json

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key.",
    "docs_url": "https://platform.scriptivox.com/docs/api-reference#error-codes"
  }
}

The full list is in Error Codes.

Keeping a key secret

Never ship a key to a browser or a mobile app. Anything a user can run, a user can read. Call the API from your own server and expose your own endpoint to the client.
Never commit one. Read it from the environment: SCRIPTIVOX_API_KEY is the variable name the CLI and the MCP server both use.
A leaked key spends real money. Revoke it at /keys first, investigate second.

Webhook payloads are signed with HMAC-SHA256 keyed on your API key, so the key doubles as the shared secret for verifying callbacks — see Webhooks.