Authentication
API keys (private beta)
Section titled “API keys (private beta)”Each key belongs to exactly one Talki account. Send it as a bearer token on every REST request:
Authorization: Bearer talki_live_…talki_live_… keys access production data. talki_test_… keys are visibly
separate and make GET /v1/account return "livemode": false.
Properties worth knowing:
- Talki stores a hash. The secret is displayed once, at creation.
- Each key carries a display name, a non-secret hint, scopes, creation and last-used times, an optional expiry, and a revocation time.
- Revocation takes effect immediately.
Storage guidance
Section titled “Storage guidance”Treat the key like a database password: server-side only, encrypted at rest, and never in browser code, a mobile binary, a URL, analytics, screenshots, or support messages.
Use a different key per integration and environment. Rotate by creating the
replacement, deploying it, validating it with GET /v1/account, and only then
revoking the old key.
Scopes
Section titled “Scopes”| Scope | Current use |
|---|---|
account:read |
GET /v1/account |
calls:read |
List and retrieve calls |
The backend reserves additional appointment, contact, service, availability, and webhook-management scopes for later phases. They do not make unreleased REST endpoints available.
Requests carry only the scopes the customer granted. A call outside them fails
with insufficient_scope — distinct from plan_upgrade_required, which means
the credential is fine but the account’s plan is not.
Authentication failures
Section titled “Authentication failures”- Missing, malformed, unknown, expired, and revoked keys all return
401 invalid_credentials. They are deliberately indistinguishable. - A valid key without the endpoint’s scope returns
403 insufficient_scope. - A valid key on a plan without public API access returns
403 plan_upgrade_required. - A closed account or inactive subscription has its own stable code.
See Errors and rate limits for the response envelope.
OAuth (planned)
Section titled “OAuth (planned)”OAuth Authorization Code with PKCE is planned for multi-customer platforms. It will resolve to the same account and scopes as an API key, so REST resource paths will not change. OAuth endpoints are not available in the private beta.