# auth.md — Al-Karrada Dental Clinic Agent Registration & Authentication

This `auth.md` document defines how autonomous AI agents, clinical assistants, and MCP clients discover authentication requirements, register agent identities, and obtain credentials for **Al-Karrada Dental Clinic (`https://www.drbasam.com`)**.

- **Resource Server:** `https://www.drbasam.com`
- **Protected Resource Metadata (RFC 9728):** `https://www.drbasam.com/.well-known/oauth-protected-resource`
- **OAuth 2.0 Authorization Server Metadata (RFC 8414):** `https://www.drbasam.com/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery Metadata:** `https://www.drbasam.com/.well-known/openid-configuration`
- **Agent Registration Endpoint:** `https://www.drbasam.com/agent/auth`

---

## 1. Public vs. Authenticated Capabilities

### Anonymous / Public Access (No Token Required)
AI agents may access the following read-only clinical resources without authentication:
- Browse dental services, treatment protocols, and pricing tiers (`/services`, `/implants`).
- Read all 52 peer-reviewed clinical dental articles (`/blog`, `/blog/:slug`).
- Query public clinic working hours, GPS coordinates (`33.2983878, 44.4254053`), and contact channels.
- Invoke in-browser WebMCP tools (`document.modelContext`) for interactive search and appointment preparation.

### Authenticated Agent Access (Bearer Token or API Key Required)
Authentication is required when an agent accesses protected API or MCP management operations:
- `clinic:read` — Read structured clinic state, cases, and availability slots via `/cpanel/api.php` or `/mcp`.
- `appointments:write` — Submit verified patient lead inquiries and appointment bookings.
- `articles:read` — Retrieve structured full-text medical articles and metadata in bulk.
- `mcp:tools` — Execute remote Model Context Protocol (MCP) tools on `/mcp`.

---

## 2. Supported Agent Registration Methods

Our authorization server (`https://www.drbasam.com/.well-known/oauth-authorization-server`) advertises `agent_auth` support for three standard flows:

### Flow A: Identity Assertion (`urn:ietf:params:oauth:token-type:id-jag`)
Agents holding an Identity Assertion JWT (`id-jag`) can exchange it directly at the registration endpoint for a scoped API key or OAuth access token:

```http
POST /agent/auth HTTP/1.1
Host: www.drbasam.com
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<ID_JAG_JWT>",
  "credential_type": "api_key",
  "scopes": ["clinic:read", "appointments:write", "mcp:tools"]
}
```

### Flow B: Verified Email Registration (`verified_email`)
Agents acting on behalf of a human patient or clinic administrator can register with a verified email assertion and complete ownership claim via `https://www.drbasam.com/agent/auth/claim`.

### Flow C: Anonymous Ephemeral Credentials (`anonymous`)
Agents needing temporary scoped credentials for a single booking session can request an ephemeral `api_key` with `"identity_type": "anonymous"` and share the returned `claim_uri` (`https://www.drbasam.com/agent/auth/claim`) with the user.

---

## 3. Using Credentials in Requests

Include the issued credential as a standard `Bearer` token in the HTTP `Authorization` header:

```http
GET /cpanel/api.php?action=health HTTP/1.1
Host: www.drbasam.com
Authorization: Bearer <ISSUED_TOKEN_OR_API_KEY>
Accept: application/json
```

---

## 4. Credential Revocation

Agents or users can revoke an issued credential at any time by calling:
- **Revocation URI:** `POST https://www.drbasam.com/agent/auth/revoke`
- **OAuth Revocation Endpoint:** `POST https://www.drbasam.com/oauth/revoke`