Skip to main content

​
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:
FormatEnvironmentUse Case
clk_test_*TestDevelopment, staging, CI/CD
clk_live_*ProductionLive 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 TypePlanDatastore
clk_test_*AnyShared test datastore
clk_live_*Sandbox / Starter / Pro / TeamShared production datastore
clk_live_*EnterpriseDedicated 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:
  1. You create/revoke keys in the Dashboard
  2. Key changes are automatically synced to the co-located database
  3. 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