Authentication

Every request carries your organization's API token. Requests about one patient also name that patient's Doctronic user.

curl --fail-with-body "$DOCTRONIC_API_URL/users/" \
  -H "Authorization: Bearer $DOCTRONIC_API_TOKEN" \
  -H "X-Doctronic-User-ID: mem_01K6JGGM2G2DB4Y9KB9H9MJJ6Q"

{
  "code": "success",
  "message": "Request successful",
  "data": {
    "id": "mem_01K6JGGM2G2DB4Y9KB9H9MJJ6Q",
    "firstName": "Avery",
    "lastName": "Chen",
    "appointmentDemographicsComplete": true,
    "missingAppointmentFields": []
  }
}

Request headers

Two operations take the token alone: POST /users/, which creates the user, and POST /pharmacy/search/. The API reference lists the headers for each operation.

The SDKs send these headers for you. forUser() in TypeScript and for_user() in Python return a client that sends X-Doctronic-User-ID on every request. The two token-only operations live on the base client, as users.create and pharmacy.search; every other operation is only on the user-scoped client.

The user ID is an identifier, not a credential. Doctronic checks that the user belongs to the organization that owns the token, so changing the header never reaches another organization's users. Your backend decides which patient a request is for; see Users.

These errors repeat until you fix the token, the header, or your user mapping, so stop and check them rather than retrying. See Errors for every other status.

Scopes

Each operation requires one scope, such as patients:read, chats:send_message, or appointments:book. The 403 example on each operation's API reference page names its scope. Tokens Doctronic issues today hold every scope.

A token without the required scope gets 403 error.auth.insufficient_scope. data.requiredScope names the missing scope:

{
  "code": "error.auth.insufficient_scope",
  "message": "This API key does not have the scope this endpoint requires.",
  "data": {
    "requiredScope": "patients:read"
  }
}

The response also carries the scope in a standard OAuth WWW-Authenticate header:

WWW-Authenticate: Bearer error="insufficient_scope", scope="patients:read"

Retrying with the same token returns the same 403. Log data.requiredScope and ask your Doctronic contact for a token that holds it.

Environments

Each environment has its own credentials. Keep separate tokens, configuration, user-ID mappings, logs, and deployment controls for staging and production.

The SDKs pick the base URL from their environment option or DOCTRONIC_ENVIRONMENT, and target staging when neither is set; see configure the client.

The legacy word partners survives in these hostnames, in operation IDs, and in some wire values such as error.partner.chat_not_found. It means the same thing as organization.

Get access

Doctronic provisions access manually; there is no self-service dashboard. To request a staging token, email business@doctronic.ai or your Doctronic contact with:

• your organization and technical owner
• the environment you need
• the product workflow you're building, and whether it uses conversations, consultation documents, or appointments
• who should receive the credential

Doctronic delivers the token through a secure channel agreed with your organization. Production access follows a completed staging integration; see Launch.

Coordinate token rotation and revocation with your implementation contact. Before a rotation, make sure your backend can load a new secret without a code change or client release. After it, send a request in the target environment, then delete the old secret from your systems.

Keep the token on your backend

The API token authorizes your organization's whole Doctronic API scope. Store it in a server-side secret manager, inject it only into the backend service that calls Doctronic, and limit which services and operators can read it. Treat webhook secrets the same way.

Do not put the token in:

• browser JavaScript or mobile app binaries
• source control or client-visible configuration
• model prompts or conversation context
• logs, traces, screenshots, or analytics events

Your frontend talks to your backend, and your backend calls Doctronic. To show a streamed reply, your backend relays the stream events to the client; the token never leaves your backend.