Authentication

Every public API request uses an environment-scoped API key as a Bearer credential.

Create an API Key

Open Developers → API keys in Atlas, choose sandbox or live, and create a key. The full secret is shown only when the key is created or rotated; store it in your secret manager immediately.

The key’s environment is part of its authorization context. A sandbox key can only reach sandbox users, health data, and device connections. A live key can only reach the live plane. Atlas keeps webhook and event views isolated by the same environment choice.

Send the Key

Set the Authorization header on every /v1 request:

curl "https://atlas.sonarhealth.co/v1/users" \
  -H "Authorization: Bearer $SONAR_API_KEY"

import os
import requests

response = requests.get(
    "https://atlas.sonarhealth.co/v1/users",
    headers={"Authorization": f"Bearer {os.environ['SONAR_API_KEY']}"},
)

const response = await fetch("https://atlas.sonarhealth.co/v1/users", {
  headers: { Authorization: `Bearer ${process.env.SONAR_API_KEY}` },
});

Missing, malformed, disabled, deleted, or rotated keys return 401:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is not valid."
  }
}

A request without a Bearer credential returns the same status with the code unauthenticated.

Billing Access

Billing must be active before Atlas allows you to create or manage keys, or before a key can make API requests.

An active subscription and the seven-day payment grace period allow key management and both sandbox and live traffic. If billing becomes blocked, Developers actions in Atlas and all API requests return 402 billing_subscription_required. Removing the Developers plan returns 402 developer_subscription_required.

{
  "error": {
    "code": "billing_subscription_required",
    "message": "An active subscription is required for API access."
  }
}

The key remains valid while access is blocked. Calls resume with the same secret after billing or the Developers plan is restored.

Key Lifecycle

Atlas lets organization owners list, rename, disable, enable, rotate, and delete API keys. Rotation invalidates the previous secret immediately. Disabling a key preserves its record but stops it from authenticating.

Security Rules

• Keep API keys in backend services and secret managers.
• Never embed them in browser bundles, mobile apps, source control, or logs.
• Use separate keys for separate services so each key can be rotated independently.
• Use sandbox keys for development and tests; never copy live health data into sandbox.

All current public API calls are authenticated with an API key.

Mobile SDK Credentials

The mobile SDKs do not accept an API key in a mobile application. Your backend uses its API key to request a single-use client token for one Sonar user. The SDK exchanges that token for a narrow, renewable session used only for on-device synchronization.

Read the SDK Authentication lifecycle for client-token creation, refresh, and recovery.