Documentation Index
Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
This section provides best practices for securing your Suki APIs and SDKs.Security best practices
Token management
Following are the best practices for token management:Store Tokens Securely
Never expose
sdp_suki_token in client-side code, logs, or version control. Store tokens securely on your backend server.Handle Token Expiration
Implement token refresh logic to automatically obtain a new
sdp_suki_token when the current one expires. Call the /login endpoint with a valid to refresh.Validate JWTs
When receiving
sdp_suki_token from Suki, verify its signature using the public keys from the endpoint (Authentication JWKS) (/api/auth/.well-known/jwks-pub.json).Use Secure Partner Tokens
Your must be a standards-compliant signed with RS256 (RSA Signature with SHA-256) algorithm. Ensure your endpoint is publicly accessible and properly configured.
Webhook security
Following are the best practices for webhook security:Use HMAC authentication
Use HMAC authentication
Suki signs POSTs with HMAC-SHA-256. A secret key on your partner record is provided by Suki. Each request sends
generated-at (Unix ms) and X-API-Key (hex HMAC of generated-at, a colon, and the raw JSON body). Verify before you process the body. For the exact steps, refer to Notification webhook for Partners for more details.Use HTTPS endpoints
Use HTTPS endpoints
Your callback URL must use HTTPS protocol. Never use HTTP endpoints for webhooks.
Validate webhook payloads
Validate webhook payloads
Always validate the webhook payload structure and verify the HMAC signature before processing notifications.
Data protection
Following are the best practices for data protection:Encrypt sensitive data
Encrypt sensitive data
All data transmitted to and from Suki is encrypted using TLS 1.2. Ensure your application maintains encryption standards for data at rest.
Follow HIPAA guidelines
Follow HIPAA guidelines
Ensure your integration complies with HIPAA requirements. Obtain patient consent before sending personal data to the platform.
Minimize data exposure
Minimize data exposure
Only send the minimum required data for each API call. Avoid including unnecessary patient or provider information.
Error handling
Following are the best practices for error handling:Handle authentication errors
Handle authentication errors
If you receive a
401 Unauthorized or 403 Forbidden response, verify your sdp_suki_token is valid and not expired. Re-authenticate if necessary.Implement retry logic
Implement retry logic
For transient errors (5xx status codes), implement exponential backoff retry logic. Do not retry on 4xx client errors.
Log errors securely
Log errors securely
When logging API errors, never include tokens, passwords, or sensitive patient data in logs.