Skip to main content
Account management is only available with an institutional API key. Doctor-level API keys do not have access to these endpoints.
Institutional API keys can create and retrieve doctor accounts within their organization. Each account represents a clinician who can use the Telepatia scribe through your integration. Creating an account mints two keys for that account — a secret key (sk_…) for server-side API calls and a publishable key (pk_…) for the browser embed (see Key types). You can later rotate the secret key.

​
Creating an account

POST /v1/institutional/accounts requires email and doctorSpecialties. Optionally pass apiKeyConfig.validForDays (1–365) to control how long the minted API key stays valid — omit it to default to 365 days (1 year).
Response:
apiKey (secret) and publishableApiKey (publishable) are returned only once — store them securely. expiresAt is the UTC timestamp when the keys stop working, and apiKeyExpiresInDays echoes the lifetime that was applied. Use the secret key for server-side API calls; the publishable key is for the browser embed and cannot call the API directly.
Save the id (or your internalCode) — you can use either to retrieve the account later.

​
Retrieving an account

Look up an account by its id (acc_*) or by your own internalCode.
Response:

​
Regenerating an API key

Rotate an account’s API key with POST /v1/institutional/accounts/{account_id}/api-keys/regenerate, identifying the account by its id (acc_*) or internalCode. Optionally pass validForDays (1–365) to set the new key’s lifetime; omit it to keep the account’s default.
Response:
Regenerating revokes the previous key (after a short grace window) and returns the new raw apiKey once — update your integration before the grace window closes. Regeneration is limited to one per account every 2 minutes; exceeding it returns 429 rate_limit_exceeded. See Error Handling.