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

# Security & Best Practices

> Learn about the best practices for securing your Suki APIs

This section provides best practices for securing your Suki APIs and SDKs.

## Security best practices

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

### Token management

Following are the best practices for token management:

<CardGroup cols={2}>
  <Card title="Store Tokens Securely" icon="lock">
    Never expose `sdp_suki_token` in client-side code, logs, or version control. Store tokens securely on your backend server.
  </Card>

  <Card title="Handle Token Expiration" icon="clock">
    Implement token refresh logic to automatically obtain a new `sdp_suki_token` when the current one expires. Call the `/login` endpoint with a valid <Tooltip tip="A secure, digitally signed JWT issued by a partner's identity provider after user authentication, passed to Suki SDK for user verification." cta="View in Glossary" href="/Glossary/p">partner token</Tooltip> to refresh.
  </Card>

  <Card title="Validate JWTs" icon="check-circle">
    When receiving `sdp_suki_token` from Suki, verify its signature using the public keys from the <Tooltip tip="JSON Web Key Set. A set of keys containing the public keys used to verify any JWT issued by the authorization server." cta="View in Glossary" href="/Glossary/j">JWKS</Tooltip> endpoint ([Authentication JWKS](/api-reference/authentication/jwks)) (`/api/auth/.well-known/jwks-pub.json`).
  </Card>

  <Card title="Use Secure Partner Tokens" icon="lock">
    Your <Tooltip tip="A secure, digitally signed JWT issued by a partner's identity provider after user authentication, passed to Suki SDK for user verification." cta="View in Glossary" href="/Glossary/p">partner token</Tooltip> must be a standards-compliant <Tooltip tip="JSON Web Token. A compact, URL-safe means of representing claims used for authentication and information exchange." cta="View in Glossary" href="/Glossary/j">JWT</Tooltip> signed with RS256 (RSA Signature with SHA-256) algorithm. Ensure your <Tooltip tip="JSON Web Key Set. A set of keys containing the public keys used to verify any JWT issued by the authorization server." cta="View in Glossary" href="/Glossary/j">JWKS</Tooltip> endpoint is publicly accessible and properly configured.
  </Card>
</CardGroup>

### Webhook security

Following are the best practices for webhook security:

<AccordionGroup>
  <Accordion icon="lock" title="Use HMAC authentication">
    Suki signs <Tooltip tip="A mechanism that allows Suki to send real-time event notifications to your application's server." cta="View in Glossary" href="/Glossary/w">webhook</Tooltip> 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](/documentation/webhook/signature-verification) for more details.
  </Accordion>

  <Accordion icon="lock" title="Use HTTPS endpoints">
    Your <Tooltip tip="A mechanism that allows Suki to send real-time event notifications to your application's server." cta="View in Glossary" href="/Glossary/w">webhook</Tooltip> callback URL must use HTTPS protocol. Never use HTTP endpoints for webhooks.
  </Accordion>

  <Accordion icon="lock" title="Validate webhook payloads">
    Always validate the webhook payload structure and verify the HMAC signature before processing notifications.
  </Accordion>
</AccordionGroup>

### Data protection

Following are the best practices for data protection:

<AccordionGroup>
  <Accordion icon="shield-check" title="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.
  </Accordion>

  <Accordion icon="shield-check" title="Follow HIPAA guidelines">
    Ensure your integration complies with HIPAA requirements. Obtain patient consent before sending personal data to the platform.
  </Accordion>

  <Accordion icon="shield-check" title="Minimize data exposure">
    Only send the minimum required data for each API call. Avoid including unnecessary patient or provider information.
  </Accordion>
</AccordionGroup>

### Error handling

Following are the best practices for error handling:

<AccordionGroup>
  <Accordion icon="triangle-exclamation" title="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.
  </Accordion>

  <Accordion icon="triangle-exclamation" title="Implement retry logic">
    For transient errors (5xx status codes), implement exponential backoff retry logic. Do not retry on 4xx client errors.
  </Accordion>

  <Accordion icon="triangle-exclamation" title="Log errors securely">
    When logging API errors, never include tokens, passwords, or sensitive patient data in logs.
  </Accordion>
</AccordionGroup>

For more details on security and compliance, see the [Security FAQs](/documentation/faqs/security).