Authentication & API Keys

Every request to the DELPHOS API must include a valid API key. Keys are scoped to a tenant (clinic or organization) and carry permissions that control which endpoints and data the key can access.

Obtaining an API Key

API keys are provisioned during onboarding. Contact your DELPHOS account representative or generate one from the administration panel.

Each key is a random token that looks like:

dph_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using the API Key

Pass the key in the x-api-key header on every request:

curl -X GET "https://your-instance.delphos.app/v1/patients" \
  -H "x-api-key: dph_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json"

import httpx

client = httpx.Client(
    base_url="https://your-instance.delphos.app/v1",
    headers={"x-api-key": "dph_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},
)

response = client.get("/patients")
print(response.json())

const response = await fetch(
  "https://your-instance.delphos.app/v1/patients",
  {
    headers: {
      "x-api-key": "dph_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

Base URL

All API endpoints are served under:

https://your-instance.delphos.app/v1/

Replace your-instance with the subdomain assigned to your organization during setup.

Tenant Isolation

Each API key is bound to a single tenant. All queries automatically filter data to that tenant — you cannot read or modify data belonging to other organizations. This isolation is enforced at the database level through row-level security policies.

Error Responses

If authentication fails, the API returns one of these responses:

Status	Meaning
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Valid key, but insufficient permissions for this endpoint

{
  "detail": "Invalid or missing API key"
}

Key Management Best Practices

Rotate keys periodically — Generate a new key, update your application, then revoke the old one.
Use environment variables — Store keys in DELPHOS_API_KEY or your secrets manager, never in source files.
Separate keys per environment — Use different keys for development, staging, and production.
Monitor usage — The administration panel shows request counts per key, making it easy to detect anomalies.

Next Steps

Your First API Call — Make your first request
Core Concepts — Understand the DELPHOS platform model