Security & Best Practices

Best practices for securing your Suki APIs

Overview

This section provides best practices for securing your Suki web SDK. These best practices are applicable to all Suki APIs.

Security Best Practices

All API requests must use HTTPS (TLS 1.2 or higher) to ensure data encryption in transit. Never send requests over unencrypted HTTP connections.

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 partner_token to refresh.

Validate JWTs

When receiving sdp_suki_token from Suki, verify its signature using the public keys from the JWKS endpoint (/api/auth/.well-known/jwks-pub.json).

Use secure partner tokens

Your partner_token must be a standards-compliant JWT signed with RS256 (RSA Signature with SHA-256) algorithm. Ensure your JWKS endpoint is publicly accessible and properly configured.

Webhook Security

Following are the best practices for webhook security:

Use HMAC authentication

Suki supports HMAC (Hash-based Message Authentication Code) for webhook authentication. Implement HMAC verification to ensure webhook requests originate from Suki.

Use HTTPS endpoints

Your webhook callback URL must use HTTPS protocol. Never use HTTP endpoints for webhooks.

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

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

Ensure your integration complies with HIPAA requirements. Obtain patient consent before sending personal data to the platform.

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

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

For transient errors (5xx status codes), implement exponential backoff retry logic. Do not retry on 4xx client errors.

Log errors securely

When logging API errors, never include tokens, passwords, or sensitive patient data in logs.

For more details on security and compliance, see the Security FAQs.