Authentication - Helios API Documentation

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

Go to heliosai.health and log in to your account.

Navigate to API Keys

Click on API Keys in the left sidebar.

Create a New Key

Click Create New Key and give it a descriptive name (e.g., “Production API” or “Development API”).

Copy Your Key

Copy the key immediately - it won’t be shown again. Keys start with sk_live_.

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

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):

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 '{ ... }'

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 '{ ... }'

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({ ... })
});

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={ ... }
)

Managing API Keys

From the Dashboard 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)

Store your webhook secret securely in your server’s environment variables. See Webhooks for signature verification implementation.

Security Best Practices

Use environment variables

Never hardcode API keys in your source code. Use environment variables:

# .env file (never commit this!)
HELIOS_API_KEY=sk_live_your_api_key_here

// Access in your code
const apiKey = process.env.HELIOS_API_KEY;

Use separate keys for environments

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

Rotate keys periodically

While not required, rotating API keys periodically is a security best practice:

Create a new key
Update your application to use the new key
Verify the new key works
Revoke the old key

Monitor key usage

Check the Last Used column in the Dashboard to monitor key activity. If you see unexpected usage patterns, consider rotating your keys.

Error Responses

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

{
  "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

Make Your First Call

Follow the quickstart guide to test your API key.

Set Up Webhooks

Configure secure webhook delivery for results.

​Getting Your API Key

​Using Your API Key

​Managing API Keys

​Webhook Secret

​Security Best Practices

​Error Responses

​Next Steps

Make Your First Call

Set Up Webhooks

Getting Your API Key

Using Your API Key

Managing API Keys

Webhook Secret

Security Best Practices

Error Responses

Next Steps