> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosai.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Helios API

All API requests must be authenticated using an API key. This guide covers how to get your key and use it securely.

## Getting Your API Key

<Steps>
  <Step title="Log in to the Dashboard">
    Go to [heliosai.health](https://www.heliosai.health) and log in to your account.
  </Step>

  <Step title="Navigate to API Keys">
    Click on **API Keys** in the left sidebar.
  </Step>

  <Step title="Create a New Key">
    Click **Create New Key** and give it a descriptive name (e.g., "Production API" or "Development API").
  </Step>

  <Step title="Copy Your Key">
    Copy the key immediately - it won't be shown again. Keys start with `sk_live_`.
  </Step>
</Steps>

<Warning>
  Keep your API keys secure. Never expose them in client-side code, public repositories, or logs.
</Warning>

## Using Your API Key

Include your API key in the `x-api-key` header with every request. The same API key works for all endpoints (`/api/v1/agent` and `/api/v1/lab-results`):

<CodeGroup>
  ```bash EHR Agent theme={null}
  curl -X POST https://api.heliosai.health/api/v1/agent \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk_live_your_api_key_here" \
    -d '{ ... }'
  ```

  ```bash Lab Results Agent theme={null}
  curl -X POST https://api.heliosai.health/api/v1/lab-results \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk_live_your_api_key_here" \
    -d '{ ... }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.heliosai.health/api/v1/agent', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.HELIOS_API_KEY
    },
    body: JSON.stringify({ ... })
  });
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      'https://api.heliosai.health/api/v1/agent',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': os.environ['HELIOS_API_KEY']
      },
      json={ ... }
  )
  ```
</CodeGroup>

## Managing API Keys

From the [Dashboard](https://www.heliosai.health) Settings page, you can:

| Action         | Description                              |
| -------------- | ---------------------------------------- |
| **Create**     | Generate new API keys with custom names  |
| **View**       | See when keys were created and last used |
| **Revoke**     | Immediately disable individual keys      |
| **Revoke All** | Emergency disable all keys at once       |

## Webhook Secret

Your webhook secret is used to verify that incoming webhooks are authentic. You can generate and manage it from the same Settings page:

| Action         | Description                                         |
| -------------- | --------------------------------------------------- |
| **Generate**   | Create a new webhook secret (shown once)            |
| **Regenerate** | Replace with a new secret (invalidates the old one) |

<Tip>
  Store your webhook secret securely in your server's environment variables. See [Webhooks](/webhooks) for signature verification implementation.
</Tip>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use environment variables" icon="lock">
    Never hardcode API keys in your source code. Use environment variables:

    ```bash theme={null}
    # .env file (never commit this!)
    HELIOS_API_KEY=sk_live_your_api_key_here
    ```

    ```javascript theme={null}
    // Access in your code
    const apiKey = process.env.HELIOS_API_KEY;
    ```
  </Accordion>

  <Accordion title="Use separate keys for environments" icon="code-branch">
    Create separate API keys for development, staging, and production. This allows you to:

    * Track usage per environment
    * Revoke compromised keys without affecting production
    * Set up different webhook URLs per environment
  </Accordion>

  <Accordion title="Rotate keys periodically" icon="rotate">
    While not required, rotating API keys periodically is a security best practice:

    1. Create a new key
    2. Update your application to use the new key
    3. Verify the new key works
    4. Revoke the old key
  </Accordion>

  <Accordion title="Monitor key usage" icon="chart-line">
    Check the **Last Used** column in the Dashboard to monitor key activity. If you see unexpected usage patterns, consider rotating your keys.
  </Accordion>
</AccordionGroup>

## Error Responses

If authentication fails, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

Common causes:

* Missing `x-api-key` header
* Invalid or revoked API key
* Key from a different account

## Next Steps

<CardGroup cols={2}>
  <Card title="Make Your First Call" icon="rocket" href="/quickstart">
    Follow the quickstart guide to test your API key.
  </Card>

  <Card title="Set Up Webhooks" icon="webhook" href="/webhooks">
    Configure secure webhook delivery for results.
  </Card>
</CardGroup>