Authentication

All API requests require authentication via Bearer token using your API key.

API Keys

Create developer API keys from the API Keys page. Each account can have up to 5 active keys.

Products a key may use

Each key can be limited to some of: transcription (POST /v1/asr, /v1/asr/upload and the /v1/asr/stream socket), transcription jobs (/v1/asr/jobs) and speech synthesis (/v1/tts). A request outside the key's products answers 403 with code key_scope; the stream closes with 4403. New keys may use every product unless you choose otherwise; change a key's products on the API Keys page. A key that only a server running jobs holds cannot be used to synthesise speech if it leaks.

Allowed networks

A key can be limited to the networks your servers call from: IP addresses or CIDR networks such as 203.0.113.0/24, set on the API Keys page. A request from any other address answers 403 with code key_network_not_allowed; the stream sends an error frame with that code and closes with 4403. The refusal does not repeat the address it came from. A key with no networks set is accepted from anywhere.

Developer terms

When Phonetico requires acceptance of a new version of the developer terms, every request your keys make answers 403 with code terms_not_accepted until you accept it in the portal; the stream sends an error frame with that code and closes with 4403. The refusal names each document and its version. Signing in to the portal, billing and your data stay available.

Monthly spend cap

Each key can have a cap on what it spends from your balance in a calendar month (UTC), set on the API Keys page. Free minutes do not count toward it; what the key's calls in progress hold does. A call that would pass the cap is refused before any work, with 402 and code key_spend_cap; a transcription job fails with the same code, and a stream sends a key_spend_cap error frame.

Expiry and rotation

A key can be given an end when it is created, up to 730 days away; after it, requests with the key are refused as if it had been revoked. Rotating a key issues a new secret for the same key and shows it once. The previous secret keeps working for 1440 minutes, so you can deploy the new one before the old one stops. Rotate after any suspicion that a secret was exposed; revoke a key you no longer use.

Two key types

Phonetico issues two key types. Both work with the same Bearer-token shape; they differ in who creates them, how they bill, and what voice modes they unlock.

Prefix	Type	Issued to	Metering	TTS voice modes
pk_live_	Developer	Self-serve at `/keys` after signup.	Dollar balance per account (top up at `/billing`); charges per ASR minute or per TTS character × tier.	Preset + custom-reference (after rights attestation).
dk_live_	Device	Phonetico's own iOS / Android apps. Not self-serve.	Free tier: 60 ASR minutes + 1,500 TTS chars per month per device. Premium upgrade via subscription. Calls logged with `cost = 0`.	Preset or custom reference. A reference clip may run up to `deviceMaxReferenceAudioSeconds`; custom-voice synthesis draws on the same monthly characters. Quality tier requires premium.

Third-party apps (anyone building on Phonetico) use developer keys. Live quota and rate values are at GET /v1/asr/limits and GET /v1/tts/limits.

Important

API keys are shown only once when created. Copy and store them securely. If you lose a key, revoke it and create a new one.

Bearer Token

Include your API key in the Authorization header:

HTTP

Authorization: Bearer pk_live_a1b2c3d4e5f67890

Security best practices

1.Never expose keys in client-side code. API calls should go through your backend server.
2.Use environment variables. Store keys in .env files, not source code.
3.Rotate keys regularly. Revoke old keys and create new ones periodically.
4.Use separate keys for environments. Create different keys for development, staging, and production.

Error responses

Authentication failures return HTTP 401:

JSON

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}