> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medera.info/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Overview

> How to authenticate to the Medera API

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

<CardGroup cols={3}>
  <Card title="session JWT" icon="https://mintcdn.com/medera-357fd587/n1mgcc3nR2sq_PoL/icons/ui/user.svg?fit=max&auto=format&n=n1mgcc3nR2sq_PoL&q=85&s=72a09e55fdd461ad74c120bd96cdf1c3" href="/authentication/quickstart" width="40" height="40" data-path="icons/ui/user.svg">
    End-user requests from a clinician or admin. Issued by the identity provider on sign-in. Header `Authorization: Bearer <jwt>`.
  </Card>

  <Card title="Developer API Key" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/key.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=4ef54e51baa6c73498065cb90a8834ff" href="/authentication/creating-clients" width="40" height="40" data-path="icons/ui/key.svg">
    Server-to-server, scoped to a project. Issued by the [Console](https://medera.info/contact). Header `X-API-Key: <key>`.
  </Card>

  <Card title="Internal service key" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/server.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=419656a675042e606aca235afc5f7e5c" href="/authentication/environments-tenants" width="40" height="40" data-path="icons/ui/server.svg">
    AI Services ↔ Backend proxy. Header `X-Service-Key: <key>`. Internal use only.
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Authentication">
    `authenticateToken` (session JWT) or `authenticateApiKey` (Developer API Key).
  </Step>

  <Step title="Tenant context">
    `setTenantContext` injects `organization_id` into the managed Postgres session via `SET LOCAL app.current_organization_id = '...'`.
  </Step>

  <Step title="PHI audit logging">
    `phiAuditMiddleware` writes a hash-chained event per HIPAA §164.312(b).
  </Step>

  <Step title="Purpose-based access">
    `purposeBasedAccess(resource,...purposes)` restricts the request to the allowed purposes: `TREATMENT`, `PAYMENT`, `OPERATIONS`, `EMERGENCY`.
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="https://mintcdn.com/medera-357fd587/n1mgcc3nR2sq_PoL/icons/ui/zap.svg?fit=max&auto=format&n=n1mgcc3nR2sq_PoL&q=85&s=279c57d41af922abbba25c4afddfc3fe" href="/authentication/quickstart" width="40" height="40" data-path="icons/ui/zap.svg">
    Get a token in 60 seconds.
  </Card>

  <Card title="Creating Clients" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/key.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=4ef54e51baa6c73498065cb90a8834ff" href="/authentication/creating-clients" width="40" height="40" data-path="icons/ui/key.svg">
    Generate Developer API Keys.
  </Card>

  <Card title="Environments & Tenants" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/server.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=419656a675042e606aca235afc5f7e5c" href="/authentication/environments-tenants" width="40" height="40" data-path="icons/ui/server.svg">
    Sandbox, staging, production.
  </Card>

  <Card title="Security Best Practices" icon="https://mintcdn.com/medera-357fd587/n1mgcc3nR2sq_PoL/icons/ui/shield-check.svg?fit=max&auto=format&n=n1mgcc3nR2sq_PoL&q=85&s=6909d120dcab3cdfef838294f042d00c" href="/authentication/security-best-practices" width="40" height="40" data-path="icons/ui/shield-check.svg">
    Five rules for credentials.
  </Card>
</CardGroup>