Authentication

API keys

A key belongs to one Talki account. Send it as a bearer token on every request:

Authorization: Bearer talki_live_…

talki_live_… keys act on production data. talki_test_… keys belong to a sandbox and make GET /v1/account return "livemode": false.

Account owners mint keys in the Talki app; there is no API for it. A platform serving many accounts uses OAuth instead.

• The secret is shown once, at creation, and cannot be retrieved later.
• A key carries a display name, a non-secret hint, scopes, timestamps, an optional expiry and a revocation time.
• Revocation takes effect immediately.

Format

After the prefix a key has 49 characters: 43 random, then a 6-character checksum. Some keys have 43 characters and no checksum; both forms are valid. Store the key as an opaque string, and do not validate its length beyond what your secret store needs.

The checksum lets a secret scanner or a paste handler reject a mistyped key without calling Talki: it is the CRC-32 of everything before it — prefix included — written in base62 (0-9A-Za-z, most significant digit first, zero-padded to 6). It is not a security control; anyone can compute it.

Storage

Server-side, encrypted at rest, one key per integration and environment.

Expiry and rolling

A key can be given an expiry, at most two years ahead. After it, the key is refused like a revoked one.

To replace a key without downtime, the owner rolls it in the Talki app: a new key with the same name, scopes and version pin is issued at once, and the old one keeps working for 24 hours by default, or stops immediately if it leaked. Deploy the new key, check it with GET /v1/account, and let the old one lapse. A key can be rolled once; roll its replacement next time.

Scopes

Read and write are separate scopes; request only the ones your integration uses.

Scope	Grants
account:read	Read the authenticated account, its locations, and its assistant settings, phone setup, usage, voices, working hours, closures and special openings
account:write	Change the assistant’s settings and the forwarding number, run a forwarding check, complete onboarding, replace the working hours, and manage closures and special openings
calls:read	List, sync, retrieve, count and export calls, their statistics, and refused calls. An export carries the calls’ appointments only with appointments:read too
calls:write	Mark calls read or unread, and archive or restore them
calls:delete	Delete calls for good, with their transcript, unresolved requests and pending contacts
transcripts:read	Retrieve the automatic transcript of a call
appointments:read	Sync and retrieve appointments
appointments:write	Create, reschedule, cancel, and restore appointments
contacts:read	Sync and retrieve curated contacts, pending contacts, tags, and VIP and blocked numbers
contacts:write	Upsert and delete contacts, approve or discard pending contacts, manage tags, and manage VIP and blocked numbers
services:read	Sync and retrieve services
services:write	Create a service with a fixed duration, update the safe writable service fields, and delete a service
resources:read	Sync and retrieve capacity: resources, unit classes, service links
resources:write	Create a shared resource, rename a resource, set the capacity of a shared one, and delete a resource
unresolved:read	Sync and retrieve questions the assistant could not answer
unresolved:write	Resolve, dismiss or reopen those questions, and set their answer
knowledge:read	List and retrieve the assistant’s knowledge-base documents, their indexing status, the text read from them, a website’s pages, and the original uploaded files
knowledge:write	Add, replace, rename, switch off and delete knowledge-base documents and a website’s pages, look for a site’s pages, and teach the assistant the answer to a resolved question. What it adds, the assistant tells every caller
availability:read	Query bookable windows

calls:read does not include transcripts:read, calls:write does not include calls:delete, and neither unresolved:write nor knowledge:read includes knowledge:write. transcripts:read, calls:delete and knowledge:write are opt-in: the account owner grants each on its own, never through a preset, so an integration that reads transcripts, deletes calls or writes the knowledge base asks for the scope explicitly and handles insufficient_scope when the owner leaves it out.

OAuth apps request the same scopes; see OAuth apps.

On resources, writing is narrower than reading: unit classes and existing service links are read-only, a capacity below what is already booked is refused, and so is deleting the default resource or one a service still needs. See Configure the assistant for the settings account:write changes.

A request outside the key’s grants fails with insufficient_scope. That is not plan_upgrade_required, which means the credential is valid but the account’s plan does not include the REST API, nor plan_feature_unavailable, which means the plan includes the API but not the feature asked for: a custom call_opening, or exporting calls over a date range.

Failures

• Malformed, unknown, expired and revoked keys all return 401 invalid_credentials, indistinguishably. A request with no credential gets the same code with a message saying none was supplied.
• Twenty failed authentications in a minute from one address block every request from it for the rest of the minute with 429 ip_rate_limited — valid keys included. A broken deployment retrying a bad key can lock out a healthy one on the same egress address.
• A valid key without the endpoint’s scope returns 403 insufficient_scope.
• A valid key on a plan without API access returns 403 plan_upgrade_required.
• A closed account or an inactive subscription has its own stable code.

See Errors and rate limits for the response envelope.

OAuth

Authorization code with PKCE, for platforms that serve many Talki accounts. A token reaches the same account, paths and scopes as a key. See OAuth apps.