Authentication

All Scribe API endpoints require authentication via an API key passed as a Bearer token in the Authorization header.

Key types

Creating a doctor account returns two API keys:

Secret key (sk_…) — your server-side credential. Use it as the Authorization: Bearer token for every request in this documentation. Keep it on your backend; never expose it in a browser.
Publishable key (pk_…) — a browser credential for the Telepatia embeddable recorder. It is exchange-only: the embed trades it for a short-lived session token that carries your account’s read and write access. A pk_ key cannot call the Scribe API directly — presenting it as a Bearer token to any endpoint returns 403 permission_denied.

Unless noted otherwise, “API key” in this documentation refers to your secret key.

Getting your API key

Contact your Telepatia account manager to obtain an API key for your institution.

Making authenticated requests

Include the API key in every request:

curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "123456789",
    "notes": "Patient reports headache",
    "pastMedicalHistory": "Hypertension, Diabetes Type 2",
    "consultationInternalId": "CONSULT-12345",
    "scribeSessionModality": "IN_PERSON"
  }'

See Overview for the base URL.

API key expiration

API keys expire. Institutional keys are minted with a lifetime (default 365 days, configurable via apiKeyConfig.validForDays when creating an account). Once a key is past its expiry, requests fail with 401 and the same “Invalid API key.” response as a revoked or unknown key. To restore access, regenerate the account’s key and update your integration with the new value.

Error responses

Status	Meaning
`401`	Missing or invalid API key
`403`	API key does not have permission for this operation

Example: Missing API key

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "API key is required."
  }
}

Example: Invalid API key

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid API key."
  }
}

Example: Publishable key used directly

A publishable (pk_) key cannot call the API directly — exchange it for a session token first, or use your secret key.

{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "Publishable keys cannot call the API directly; exchange one for a session token first, or use a secret key."
  }
}

Getting Started

Consultations

Scribe Sessions

Clinical Decision Support

Webhooks

Smart Templates

Session Templates

Accounts

Patients

Reference

Key types

Getting your API key

Making authenticated requests

API key expiration

Error responses

Example: Missing API key

Example: Invalid API key

Example: Publishable key used directly

​Key types

​Getting your API key

​Making authenticated requests

​API key expiration

​Error responses

​Example: Missing API key

​Example: Invalid API key

​Example: Publishable key used directly

Key types

Getting your API key

Making authenticated requests

API key expiration

Error responses

Example: Missing API key

Example: Invalid API key

Example: Publishable key used directly