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

Every API key carries scopes, and the API checks them on each request:

read — GET operations
write — POST, PATCH and DELETE operations

Keys created in the Dashboard carry both read and write. A request outside a key’s scopes is refused with 403 and the error code INSUFFICIENT_SCOPE. A key with no scopes at all is refused. Live keys (clk_live_) can be created only by an organization owner or admin, and only on a paid plan. Test keys (clk_test_) are available on every plan.

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