# Authentication & Access Guide for AI Agents

> Reference guide for AI agents, LLM assistants, and automated clients interacting with Recovery TLV.
> Conforms strictly to the WorkOS [auth.md](https://github.com/workos/auth.md) specification and RFC 9728 / RFC 8414 standards.

## Overview

Recovery TLV provides an open, unauthenticated, read-only clinical knowledge and dataset API for AI agents and clinical researchers:
- **Free, and there is no paid tier:** every machine resource is public and read-only. Nothing here is metered or billed.
- **Token endpoints exist for client compatibility only:** `POST /api/v1/auth/keys` and `/auth/token` return a bearer token so OAuth-shaped clients can finish their flow. The token is **not required and not validated** - requests without it are served identically.
- **Sandbox:** `GET /api/v1/sandbox` returns a deterministic mock payload for integration testing. It reads the same static data; there is no separate test environment because there is nothing to mutate.
- **Authentication Required:** **None** for public read endpoints (Unauthenticated public read). Optional Bearer tokens supported.
- **Base URL:** `https://recoverytlv.co.il/api/v1`
- **Protocol:** HTTPS GET/HEAD with optional Bearer token authorization and RFC 9110 Idempotency-Key support.
- **Specification:** `https://recoverytlv.co.il/openapi.json`

```yaml
agent_auth:
  auth_type: "none"
  supported_flows:
    - "unauthenticated_public_read"
    - "service_auth"
    - "anonymous"
  identity_endpoint: "https://recoverytlv.co.il/api/v1/openapi.json"
  claim_endpoint: "https://recoverytlv.co.il/booking/"
  identity_types_supported:
    - "anonymous"
    - "service_auth"
    - "identity_assertion"
  service_auth:
    token_endpoint: "https://recoverytlv.co.il/api/v1/auth/token"
    registration_endpoint: "https://recoverytlv.co.il/api/v1/auth/register"
  identity_assertion:
    assertion_types_supported:
      - "urn:ietf:params:oauth:token-type:id-jag"
  skill: "https://recoverytlv.co.il/auth.md"
  scope_inventory:
    - scope: "read:clinical_data"
      description: "Read clinical conditions index, medical codes (ICD-10/11, SNOMED, MeSH), and reimbursement data."
    - scope: "read:clinic_facts"
      description: "Read clinic location, opening hours, flat pricing (₪480), and therapist credentials."
```

---

## 1. Discover

Agents discover authentication capabilities and machine-readable metadata via standard endpoints:

| Protocol / Standard | Path | Media Type | Purpose |
|---|---|---|---|
| OpenAPI 3.0 | `/openapi.json` | `application/json` | Primary identity_endpoint & schema definitions |
| Protected Resource Metadata | `/.well-known/oauth-protected-resource` | `application/json` | RFC 9728 resource declaration |
| Authorization Server Metadata | `/.well-known/oauth-authorization-server` | `application/json` | RFC 8414 token & registration endpoints |
| MCP Manifest | `/.well-known/mcp-manifest.json` | `application/json` | Anthropic Model Context Protocol tools |
| MCP Server Card | `/.well-known/mcp/server-card.json` | `application/json` | MCP discovery server card |
| LLM Navigation Index | `/llms.txt` | `text/plain` | Scoped clinical facts and index |
| Machine Pricing | `/pricing.md` | `text/markdown` | Transparent consultation and HMO rates |

---

## 2. Pick a method

Agents can choose between two interaction methods:

1. **Unauthenticated Public Read (Recommended):** Query `https://recoverytlv.co.il/api/v1/*` directly without credentials. All read endpoints return status `200 OK`.
2. **Service Auth / Agent Token:** For frameworks requiring a Bearer token or client credentials, obtain a free-tier token via instant self-serve registration.

---

## 3. Register

For clients that require explicit client registration, Recovery TLV provides an automated registration endpoint per RFC 7591:

```http
POST /api/v1/auth/register HTTP/1.1
Host: recoverytlv.co.il
Content-Type: application/json

{
  "client_name": "AutonomousAgent/1.0",
  "grant_types": ["client_credentials", "urn:ietf:params:oauth:token-type:id-jag"]
}
```

The server immediately returns `client_id` and `client_secret` without requiring approval or email validation.

---

## 4. Claim

When an agent needs to perform an action on behalf of a human user (such as scheduling an appointment), the agent claims access via the designated `claim_endpoint`:

- **Claim URL:** `https://recoverytlv.co.il/booking/` (English: `/booking/en/`)
- **Direct WhatsApp:** `https://wa.me/972507171222`
- **Policy:** Recovery TLV maintains **NO automated write booking API**. The agent must present the claim URL to the human user to confirm a slot. Never fabricate booking confirmations.

---

## 5. Exchange

To mint or exchange credentials (such as an `id-jag` identity assertion) for an access token:

```http
POST /api/v1/auth/token HTTP/1.1
Host: recoverytlv.co.il
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=read:clinical_data
```

Or for instant self-serve key generation:

```http
POST /api/v1/auth/keys HTTP/1.1
Host: recoverytlv.co.il
```

Response:
```json
{
  "access_token": "rtlv_free_agent_token",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "scope": "read:clinical_data read:clinic_facts"
}
```

---

## 6. Use the access_token

Pass the minted access token in the standard HTTP `Authorization` header:

```http
GET /api/v1/data/condition-medical-codes-he.json HTTP/1.1
Host: recoverytlv.co.il
Authorization: Bearer rtlv_free_agent_token
```

Clients may also supply `Idempotency-Key` headers for safe retries per RFC 9110.

---

## 7. Errors

When authentication or authorization fails on protected routes, the server returns `HTTP 401 Unauthorized` carrying a standard `WWW-Authenticate` challenge header:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://recoverytlv.co.il/.well-known/oauth-protected-resource"
Content-Type: application/problem+json

{
  "type": "https://recoverytlv.co.il/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired token. Generate a new key at /api/v1/auth/keys.",
  "instance": "/api/v1/auth/keys"
}
```

---

## 8. Revocation

Tokens may be revoked via RFC 7009 token revocation:

```http
POST /api/v1/auth/revoke HTTP/1.1
Host: recoverytlv.co.il
Content-Type: application/x-www-form-urlencoded

token=rtlv_free_agent_token
```

Because Recovery TLV data is public, revoked tokens do not prevent ongoing unauthenticated reads.