Skip to main content
Some partners cannot include per-user identity information 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 partners. Send partner_token in the JSON request body for Login and Register. Because the token is shared across providers, Bearer partners must also send provider_id in every Login and Register request so Suki can identify the active provider.
Important:Suki assigns your partner type during onboarding. If you are not sure whether your organization is configured as a Bearer partner, contact your partnership team. This guide applies only to Bearer partners. It does not apply to partners that use a per-user ID token or user-scoped access token as partner_token.

​
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.

​
Use cases

Use Bearer partner authentication when your integration matches one of these scenarios:

Shared Partner Token

Your backend uses a single shared partner_token for multiple clinicians, and the token does not identify the signed-in provider. Send provider_id on every Login and Register request so Suki can identify the correct provider.

Identity Outside the Partner Token

Your application already knows the signed-in provider, such as through a session or database record, but you cannot include that identity in the partner_token. Instead, send a stable identifier as provider_id in the authentication request body.

No Per-user ID Token

Your identity provider does not issue a per-user ID token for Suki, or you cannot add user claims to the access token. Bearer partner authentication lets you keep your existing token model and identify the provider by using provider_id.
Diagram: Tenant A, Tenant B, and Tenant C connect through shared partner tokens, then to the Suki platform.

​
How Bearer partners differ from other partners

TopicStandard partner authenticationBearer partner authentication
User identity sourceDerived from partner_tokenPassed as provider_id in the request body
partner_token typePer-user ID token or user-scoped tokenTypically one shared partner_token for many providers
provider_id on login or registerOptional and ignoredRequired
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.

​
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.

​
Login and Register request fields

Bearer partners use the same login and register endpoints as standard partners. You must include provider_id on every login and register call.

​
Login

Endpoint: LoginMethod: POST
FieldBearer partners
partner_idRequired. Partner ID from Suki.
partner_tokenRequired. Shared partner_token your integration uses for authentication.
provider_idRequired. 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
FieldBearer partners
partner_idRequired. Partner ID from Suki.
partner_tokenRequired. Shared partner_token your integration uses for authentication.
provider_idRequired. Stable identifier for the provider in your system. Use this as the user identifier at registration.
provider_nameRequired. Display name for the provider.
provider_org_idRequired. Organization the provider belongs to.
provider_specialtyOptional. 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.
Security considerationsIf an attacker gets your shared partner_token and a valid provider_id, they could try to impersonate a provider. To reduce risk:
  • Allow only trusted systems to call the login and register endpoints.
  • Monitor for suspicious or unexpected authentication activity.
  • Rotate shared partner_token values regularly when your identity provider allows it.
Last modified on June 12, 2026