Authentication Overview

Medera supports three credential types, each scoped to a tenant (organization) and an environment.

session JWT

End-user requests from a clinician or admin. Issued by the identity provider on sign-in. Header Authorization: Bearer <jwt>.

Developer API Key

Server-to-server, scoped to a project. Issued by the Console. Header X-API-Key: <key>.

Internal service key

AI Services ↔ Backend proxy. Header X-Service-Key: <key>. Internal use only.

Four-layer defense Every PHI-touching request is validated through four layers:

Authentication

authenticateToken (session JWT) or authenticateApiKey (Developer API Key).

Tenant context

setTenantContext injects organization_id into the managed Postgres session via SET LOCAL app.current_organization_id = '...'.

PHI audit logging

phiAuditMiddleware writes a hash-chained event per HIPAA §164.312(b).

Purpose-based access

purposeBasedAccess(resource,...purposes) restricts the request to the allowed purposes: TREATMENT, PAYMENT, OPERATIONS, EMERGENCY.

API key scopes

Scope	Allows
`read:data`	Read non-PHI resources (workflows, deployments, templates)
`write:data`	Create / update non-PHI resources
`execute:agents`	Trigger agent / workflow executions
`read:phi`	Read PHI (patients, sessions) — requires active BAA
`write:phi`	Write PHI — requires active BAA
`admin`	Admin operations (separate issuer)

Subscription gating

For agent / intake / therapy / copilot endpoints, the middleware stack also runs requireActiveSubscription and checkAgentLimit against the tenant’s payment processor subscription state.

Rate limits

Endpoint family	Production	Dev / staging
Read endpoints	100 req / min	10,000 req / min
Write endpoints	20 req / min	10,000 req / min
Auth (`/login`, `/register`, `/forgot-password`)	10 req / 15 min	10 req / 15 min
`/api/intake/start-batch-call`	10 req / min	10 req / min

What’s next

Quickstart

Get a token in 60 seconds.

Creating Clients

Generate Developer API Keys.

Environments & Tenants

Sandbox, staging, production.

Security Best Practices

Five rules for credentials.