Single Auth Token Authentication

Some partners use a single shared partner_token for all clinicians instead of generating a unique token for each user through their identity provider. Suki refers to this authentication model as Single Auth Token authentication. In this model, your backend authenticates every request using the same partner_token. Because the token identifies your organization rather than an individual clinician, you must provide the clinician’s identity separately. With Single Auth Token authentication, include the clinician identifier on every request:

Pass provider_id in the request body when calling Register and Login.
Pass sdp_provider_id as an HTTP header on every subsequent REST API request and WebSocket connection.

Important

Single Auth Token authentication is different from Bearer partner authentication. Bearer partners send provider_id only during Register and Login. Single Auth Token partners must also send sdp_provider_id on every subsequent REST API request and WebSocket connection.
A partner can use either Bearer partner authentication or Single Auth Token authentication, but not both.
Suki assigns your authentication model during onboarding. If you are unsure which authentication model your organization uses, contact your Suki partnership team.

Prerequisites

Before you implement Single Auth Token authentication, confirm the following:

Single Auth Token configuration: Your Suki partnership team confirms that your organization uses Single Auth Token authentication.
Stable clinician identifiers: Your application already knows the active clinician from your session, EHR, or user directory. Use the same stable provider_id for that clinician on every Register, Login, and later API request.
HTTPS required: Send Login and Register as HTTPS POST requests with a JSON body. Do not send credentials in query parameters.

How this authentication model differs

Single Auth Token partners authenticate the same way as other partners by sending partner_token, but clinician identity is not derived from that token. You provide the clinician identity separately through provider_id and sdp_provider_id.

Topic	Standard authentication	Single Auth Token authentication
Clinician identity	Derived from `partner_token`	Passed as `provider_id` on Register and Login, and as `sdp_provider_id` on later API calls
`partner_token`	Per-user ID token or user-scoped token	One shared `partner_token` for multiple clinicians
`provider_id` on Register and Login	Optional and ignored	Required
`sdp_provider_id` on later API calls	Not required for standard partners	Required on every REST API request and WebSocket connection

Single Auth Token authentication behavior

Register and Login identify the clinician using provider_id because the shared partner_token identifies your organization, not the clinician.
After Login, send sdp_provider_id on every subsequent REST API request and WebSocket connection. The token authorizes your organization. sdp_provider_id tells Suki which clinician is acting.
Use the same stable provider_id for a clinician on Register, Login, and later sdp_provider_id headers.
A partner can use either Bearer partner authentication or Single Auth Token authentication, but not both.

Typical flow

Register each clinician once with Register. Use a stable provider_id for that person.

Login with Login. Send your partner_id, shared partner_token, and the active clinician’s provider_id.

Call Suki APIs with the sdp_suki_token returned from Login. Include the sdp_provider_id header on every REST and WebSocket request.

Refresh the token before it expires (1 hour). Call Login again with the same partner_token and provider_id.

Send sdp_provider_id with all API requests

When you use Single Auth Token authentication, include the sdp_provider_id header on every Suki API request after Login.

Register and Login: Your app already knows which clinician is signing in. Send that person’s identifier as provider_id so Suki can register or authenticate them.
All other APIs: After Login, send sdp_provider_id on every REST and WebSocket request along with sdp_suki_token. Suki uses it to route the request to the correct clinician.

Register each provider with a stable provider_id before their first Login. If Login fails because the provider is not registered, call Register, then call Login again.

Single Auth Token partners use the same Login and Register endpoints as standard partners. You must include provider_id on every Login and Register call.

Endpoint: LoginMethod: POST

Field	Single Auth Token partners
`partner_id`	Required. Partner ID from Suki.
`partner_token`	Required. Shared `partner_token` your integration uses for authentication.
`provider_id`	Required. Stable identifier for the provider in your system.

Example request

curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "your-partner-id",
    "partner_token": "your-shared-partner-token",
    "provider_id": "provider-123"
  }'

On success, the API returns suki_token. Use it as the sdp_suki_token header on later API calls. Also send sdp_provider_id with the same clinician identifier on every request. The token is valid for 1 hour. To refresh it, call Login again with the same partner_token and provider_id.

Register

Register a provider once before their first Login. Refer to Provider authentication for new user, existing user, and conflict responses.

Endpoint: RegisterMethod: POST

Field	Single Auth Token partners
`partner_id`	Required. Partner ID from Suki.
`partner_token`	Required. Shared `partner_token` your integration uses for authentication.
`provider_id`	Required. Stable identifier for the provider in your system. Use this as the user identifier at registration.
`provider_name`	Required. Display name for the provider.
`provider_org_id`	Required. Organization the provider belongs to.
`provider_specialty`	Optional. Defaults to `FAMILY_MEDICINE` if omitted.

Example request

curl -X POST https://sdp.suki-stage.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "your-partner-id",
    "partner_token": "your-shared-partner-token",
    "provider_id": "provider-123",
    "provider_name": "Dr. Jane Smith",
    "provider_org_id": "org-123"
  }'

For all Register fields and response codes, refer to the Register API reference.

Get Started

Resources

Single Auth Token Authentication

Prerequisites

How this authentication model differs

Single Auth Token authentication behavior

Typical flow

Send sdp_provider_id with all API requests

Example request

Register

Example request

​Prerequisites

​How this authentication model differs

​Single Auth Token authentication behavior

​Typical flow

​Send sdp_provider_id with all API requests

​Login and Register request fields

​Login

​Example request

​Register

​Example request

Prerequisites

How this authentication model differs

Single Auth Token authentication behavior

Typical flow

Send sdp_provider_id with all API requests

Login and Register request fields

Login

Example request

Register

Example request