Concepts
API keys
The clinic's secret key: where it comes from, how to send it, and what rotation does.
Every request to API v1 is authenticated with the clinic's secret key, sent in the Authorization header. The key identifies the clinic: there is no account id or clinic id in any URL.
Send the key
Add the header to every request:
Authorization: Bearer pp_live_...curl "https://app.pozyskajpacjenta.pl/api/v1/services" \
-H "Authorization: Bearer $PP_API_KEY"All samples in this documentation read the key from the environment variable PP_API_KEY and call one base URL, https://app.pozyskajpacjenta.pl. The same paths also answer without the /api prefix on https://api.pozyskajpacjenta.pl/v1/….
Create a key
In the clinic's panel, open Ustawienia → Integracje → Klucz API and choose Wygeneruj klucz. The key starts with pp_live_ and is shown once: the platform stores only its SHA-256 digest, so nobody can show it to you again. Save it where your server reads its secrets.
What the key can do
There is one key per clinic. Without any scope it reads the site and its content, creates leads, books appointments, reads the appointment list with patient names and phone numbers, and uploads to the media library. Treat it like a password:
- keep it on your server (environment variables, a secret store), never in code that runs in a browser or in a public repository;
- call the API from your backend and pass only what the page needs to the browser;
- for a form on a site that has no backend, use the clinic's embed script and its public key (
ppe_…) instead. See Leads.
Scopes
Some things need more than that, so the clinic adds them to its key on purpose, in Ustawienia → Integracje → Klucz API → Uprawnienia klucza:
| Scope | Lets the key |
|---|---|
conversations:read | list conversations, read one with its patient, read its messages |
conversations:write | send a message to a patient on the clinic's channels |
case_studies:write | let the clinic's own AI assistant, connected with this key, create and edit case-study drafts (since 1.25.0) |
An endpoint the key has no scope for answers 403 with code: "missing_scope" and the missing scope. A key from before scopes existed has none of the conversation scopes: it keeps exactly what it could do. Every key that existed when case_studies:write was added holds it, so the drafts its assistant made keep working. Scopes belong to the clinic's API access, not to one secret: a new key keeps them. See Conversations.
Rotate a key
Generating a new key in the panel (Wygeneruj nowy (unieważnia stary)) invalidates the old one at once. There is no overlap period: update every integration that uses the key right after you rotate it, and expect 401 from anything you missed.
When the key is wrong
A missing or unknown key answers 401 with a message in error. These responses carry no RateLimit headers, because there is no key to count against.
{
"error": "missing Authorization: Bearer <klucz z panelu Ustawienia>"
}See Errors for every status and Rate limits for the per-key limit.