Skip to main content
Not a Suki Partner yet?To use the Suki APIs, you must first register your organization as a partner. To begin, follow the Partner onboarding guide to learn more or schedule a call with Suki using the Ask AI chat assistant.After you register, you use a (partner_token) to authenticate your API requests. The partner_token is a that you provide, and it is a required parameter when registering a provider. Find more details on how to get a partner_token in the Partner authentication guide.
All Suki Partner APIs require partner authentication. To authenticate, exchange your (partner_token) to get a Suki access token. Use the Suki access token to call the Register and Login APIs and authenticate clinicians with Suki. Suki access tokens are valid for 1 hour. This guide explains the two main endpoints for the authentication workflow:
  • Register user: A one-time call to register a new in the Suki system.
  • Authenticate user: Call this endpoint to get a suki_token (sdp_suki_token) for a registered provider.

​
Authentication methods

Suki supports the following authentication methods. Suki configures your method during Partner onboarding.

​
Standard partner authentication

Each clinician authenticates with their own partner_token. Suki derives provider identity from that token, so you do not need to send provider_id on Register or Login. Best for
  • Enterprise deployments where each clinician has their own account in your identity provider
  • Integrations where your IdP issues a per-user ID token or user-scoped JWT as partner_token
  • Flows where the token already identifies the signed-in provider without a separate provider_id

​
Single Auth Token authentication

Your backend uses one shared partner_token for multiple clinicians. The token proves your organization is authorized, but it does not identify who is signed in. Send provider_id on every Register, Login, and API request. Best for
  • Server backends that authenticate to Suki with one organization-level token for many clinicians
  • Applications that already know the active provider from your session, EHR, or user directory
  • Identity setups that cannot include per-user claims in the partner_token
  • Bearer partner configurations (refer to Bearer partner authentication)
If you plan to use Single Auth Token authentication, see Authentication with a Single Auth Token for more details.
  • To refresh a Suki access token, send another POST request to Login with a valid partner_token.
  • You need the Suki access token to call all Suki REST and WebSocket APIs.
If you are a Bearer partner, you must send sdp_provider_id on every REST API and WebSocket API call. Refer to Bearer partner authentication for more details.

​
Register provider/user account

Use the below endpoint to register a new provider/user in the Suki platform. You only need to do this once for each new provider.
Endpoint: RegisterMethod: POST

​
Registration scenarios

Flowchart: POST register leads to User Exists; if No, New User Registration, Create User and Link, then Response 201; if Yes, Linked to this Partner; if No, Existing User New Partner Link, Link User to Partner, then Response 201; if Yes, Existing User Already Linked, then Response 409 Conflict. The Register endpoint handles three main scenarios:
  • New user registration: If the provider does not exist in the Suki system, this call creates a new user and links them to your partner account and organization.
  • Existing user, new partner link: If the provider already exists but is not linked to your partner account, this call links them to your partner and their existing organization.
  • Existing user, already linked: If the provider is already registered and linked to your partner account, the API returns a 409 Conflict error.

​
Authenticate provider/user session

After a provider is registered, call Login endpoint to get a Suki access token (sdp_suki_token).
If you are a Bearer partner, you must send provider_id on every API call, including Login. Refer to Bearer partner authentication for more details.

​
JWKS endpoint

Suki provides a public JWKS (JSON Web Key Set) endpoint that you can use to verify the signature of the sdp_suki_token that our API returns.
Endpoint: JWKS URLMethod: GETAuthentication: None (Public)

​
Use cases

Diagram: Fetch Public Keys leads to JWKS Endpoint; from JWKS, three branches to Token Verification, Signature Validation, and Key Rotation.
  • Token verification: Fetch public keys to verify JWTs issued by Suki.
  • Signature validation: Validate the signature of the sdp_suki_token.
  • Key rotation: Automatically discover new public keys when Suki rotates our signing keys.

​
Authentication with a Single Auth Token

Some partners use one shared partner_token for all providers instead of a per-user token from their identity provider. Suki configures this during Partner onboarding. Because the shared token does not identify which clinician is signed in, your backend must send provider_id in the body of Register and Login requests and sdp_provider_id as a header on every subsequent request so Suki knows who each request is for.

​
Typical flow

1
Register each clinician once with Register. Use a stable provider_id for that person.
2
Login with Login. Send your partner_id, shared partner_token, and the active clinician’s provider_id.
3
Call Suki APIs with the sdp_suki_token returned from Login. Include the sdp_provider_id header on every REST and WebSocket request.
4
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 method for all clinicians, include the sdp_provider_id header on every Suki API request after Login. The token proves your organization is authorized; it does not identify which clinician is acting. You pass sdp_provider_id to tell Suki that.
  • 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.
For request fields, security guidance, and examples, refer to Bearer partner authentication.
Last modified on June 18, 2026