Bearer Partner Type Authentication

Some partners cannot include clinician identity in the OAuth 2.0 token they send to Suki. During onboarding, Suki configures these organizations as Bearer partners. Bearer partners authenticate the same way as other server-to-server integrations by sending partner_token in the request body of the Login and Register APIs. Because partner_token does not identify the clinician, Bearer partners must also include provider_id in every Login and Register request. Suki uses provider_id to identify the clinician and validates it against the expression configured during onboarding.

Important

Bearer authentication is not the same as Single Auth Token authentication. Bearer partners send provider_id only during Login and Register. Single Auth Token partners include clinician identity on every subsequent API request by sending sdp_provider_id. See Single Auth Token authentication.
A partner cannot use both Bearer authentication and Single Auth Token authentication.
Suki assigns your authentication type during onboarding. If you are unsure whether your organization is configured as a Bearer partner, contact your Suki partnership team.

Prerequisites

Before you implement Bearer partner authentication, confirm the following:

Bearer partner configuration - Your Suki partner contact confirms that your organization is configured as a Bearer partner.
Provider ID format - You and Suki agree on a stable provider identifier format, such as an email address or external user ID. Use the same format on every login and register call.
HTTPS required - Send Login and Register requests as HTTPS POST requests with a JSON body. Do not send credentials in query parameters.

Common integration patterns and use cases

Use Bearer partner authentication only when Suki configured this partner type during onboarding. In each pattern, your backend supplies the active provider identity separately from the shared token.

Shared Partner Token

Reuse the shared partner_token across providers, and send the active provider’s stable provider_id on every Login and Register request.

Identity Outside the Partner Token

Read the signed-in provider from your application session or identity store, then map that identity to the agreed provider_id format in the authentication request body.

No Per-User ID Token

Keep your existing shared-token model when your identity provider cannot issue a Suki-compatible per-user token. Use provider_id as the separate provider identity.

Diagram: Tenant A, Tenant B, and Tenant C connect through shared partner tokens, then to the Suki platform.

How Bearer authentication differs

Bearer partners authenticate the same way as other partners, but clinician identity is provided through provider_id instead of being derived from partner_token.

Topic	Standard authentication	Bearer authentication
Clinician identity	Derived from `partner_token`	Passed as `provider_id` in the request body
`partner_token`	Per-user ID token or user-scoped token	Typically one shared `partner_token` for multiple providers
`provider_id` on Login and Register	Optional and ignored	Required
`provider_id` validation	Not applicable	Must match the expression configured during onboarding

Bearer authentication behavior

Login and Register identify the clinician using provider_id instead of per-user claims in partner_token.
Clients, including the Web SDK, pass provider_id for Bearer partners. Other clients can do the same.
provider_id is required and must follow the format agreed during onboarding.
Bearer partners cannot have the READONLY partner access level.

In Bearer partner authentication, the partner application provides the provider identity on behalf of the signed-in user. This is different from the HTTP Authorization: Bearer header format.You still send partner_token in the JSON request body for login and register requests.

Security considerations for Bearer partnersAccepting end-user identifiers as API metadata has security implications:

Encryption: Send provider_id in the JSON body of HTTPS POST requests over TLS. Do not put credentials in query parameters.
Impersonation: Restrict Login and Register to trusted systems so impostors cannot assert another clinician’s provider_id.
Shared token risk: Unlike signed OAuth tokens, user metadata in the API body can be misused if someone obtains your shared service account partner_token. Monitor for abuse and rotate tokens when your identity provider allows it.

Authentication workflow

For Bearer partners, Suki validates partner_id and provider_id on Login. If the provider is not registered, call Register, then call Login again. The flow matches standard partners after registration. Learn more about registration scenarios in Provider authentication. Bearer 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	Bearer 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. Must match the format agreed with Suki during onboarding.

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 Ambient API calls. The token is valid for 1 hour. To refresh it, call Login again with a valid partner_token.

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	Bearer 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

Bearer Partner Type Authentication

Prerequisites

Common integration patterns and use cases

Shared Partner Token

Identity Outside the Partner Token

No Per-User ID Token

How Bearer authentication differs

Bearer authentication behavior

Authentication workflow

Example request

Register

Example request

​Prerequisites

​Common integration patterns and use cases

Shared Partner Token

Identity Outside the Partner Token

No Per-User ID Token

​How Bearer authentication differs

​Bearer authentication behavior

​Authentication workflow

​Login and Register request fields

​Login

​Example request

​Register

​Example request

Prerequisites

Common integration patterns and use cases

How Bearer authentication differs

Bearer authentication behavior

Authentication workflow

Login and Register request fields

Login

Example request

Register

Example request