Authentication

ClinikAPI uses API key authentication via the x-api-key header. Every request must include a valid key.

API Keys

Keys are created in the Developer Dashboard and follow this format:

Format	Environment	Use Case
`clk_test_*`	Test	Development, staging, CI/CD
`clk_live_*`	Production	Live patient data

curl -X GET https://api.clinikapi.com/v1/patients \
  -H "x-api-key: clk_test_abc123def456"

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

ClinikAPI is a Data API

ClinikAPI does not handle end-user authentication. You bring your own auth provider (Clerk, Auth0, Firebase, etc.) and use ClinikAPI purely for clinical data storage and retrieval.

Patient (browser) → Your Auth (Clerk/Auth0) → Your Backend → ClinikAPI SDK → ClinikAPI

The SDK runs on your server. Your backend authenticates the end user, then calls ClinikAPI with your secret key.

Tenant Isolation

Every resource stored in ClinikAPI is tagged with your organization’s tenant ID:

{
  "meta": {
    "tag": [
      {
        "system": "https://clinikapi.com/tenant",
        "code": "org_abc123"
      }
    ]
  }
}

On create: the tenant tag is automatically injected
On search: a _tag filter is automatically applied — you can only see your own data
On read/update/delete: ownership is verified before the operation proceeds

There is no way to access another tenant’s data through the API.

Multi-Datastore Routing

Requests are routed to different datastores based on your key and plan:

Key Type	Plan	Datastore
`clk_test_*`	Any	Shared test datastore
`clk_live_*`	Sandbox / Starter / Pro / Team	Shared production datastore
`clk_live_*`	Enterprise	Dedicated datastore

Enterprise customers get a fully isolated datastore provisioned in their preferred region.

Key Validation Flow

For minimal latency, API keys are validated against a co-located PostgreSQL database that mirrors your dashboard data:

You create/revoke keys in the Dashboard
Key changes are automatically synced to the co-located database
The API validates keys locally — no cross-region round trips

Keys are cached for 60 seconds to minimize database lookups.

Key Scopes

API keys can be scoped to specific permissions:

read — GET operations only
write — POST, PATCH, DELETE operations
* — full access (default)

Scopes are set when creating the key in the Dashboard.

Security Best Practices

Never expose your API key in client-side code, Git repositories, or logs.

Store keys in environment variables (CLINIKAPI_SECRET_KEY)
Use clk_test_* keys for development — they route to an isolated test datastore
Rotate keys periodically from the Dashboard
Use scoped keys when possible (e.g., read-only for analytics services)
For client-side UI, use @clinikapi/react with the proxy pattern

Getting Started

Guides

Legal

Authentication

Authentication

API Keys

ClinikAPI is a Data API

Tenant Isolation

Multi-Datastore Routing

Key Validation Flow

Key Scopes

Security Best Practices

​Authentication

​API Keys

​ClinikAPI is a Data API

​Tenant Isolation

​Multi-Datastore Routing

​Key Validation Flow

​Key Scopes

​Security Best Practices

Authentication

API Keys

ClinikAPI is a Data API

Tenant Isolation

Multi-Datastore Routing

Key Validation Flow

Key Scopes

Security Best Practices