Rotate End-User Token Secret

Mint the signing secret end-user tokens are verified against, replacing any previous one at once: every token signed with the old secret stops verifying. The plaintext is in this response and nowhere else; later reads show user_token_secret_hint. Your backend signs a JWT with it (HS256) carrying sub (the user, at most 256 characters) and exp (within 24 hours), and the consumer presents it as Authorization: Bearer <token>. Register user_token_jwks_url instead to verify with your own keys. Dark launch: requires the hosted_apis_access entitlement (402 hosted_apis_not_in_plan otherwise).

Mint the signing secret end-user tokens are verified against, replacing any previous one at once: every token signed with the old secret stops verifying. The plaintext is in this response and nowhere else; later reads show `user_token_secret_hint`. Your backend signs a JWT with it (HS256) carrying `sub` (the user, at most 256 characters) and `exp` (within 24 hours), and the consumer presents it as `Authorization: Bearer <token>`. Register `user_token_jwks_url` instead to verify with your own keys. Dark launch: requires the `hosted_apis_access` entitlement (402 `hosted_apis_not_in_plan` otherwise).

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

api_idstringRequired

Hosted API id (prefixed external id, api_...).

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

secretstring

The plaintext signing secret, present on this response only. Sign end-user tokens with it (HS256).

secret_hintstring

The masked form every later read shows as user_token_secret_hint.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error