# Auth.md

This document provides instructions for AI agents seeking programmatic access to Shilmoon Hospital APIs.

## Discovery Endpoints

- **OAuth Authorization Server Metadata**: `/.well-known/oauth-authorization-server`
- **OIDC Discovery Metadata**: `/.well-known/openid-configuration`
- **OAuth Protected Resource Metadata**: `/.well-known/oauth-protected-resource`

## Dynamic Client Registration

Agents can register programmatically by sending a `POST` request to the registration endpoint:

- **Registration URI**: `https://shilmoon.hospital/oauth/register`
- **Supported Identity Types**: `service_account`, `agent`
- **Supported Credential Types**: `client_secret`, `private_key_jwt`

### Registration Request Example

```json
{
  "client_name": "Healthcare Assistant Agent",
  "grant_types": ["client_credentials"],
  "response_types": [],
  "scope": "appointments:read appointments:write doctors:read departments:read"
}
```

## Obtaining Access Tokens

Request an access token using the Client Credentials grant:

```http
POST /oauth/token HTTP/1.1
Host: shilmoon.hospital
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=appointments:read
```

## Available Scopes

| Scope | Description |
| --- | --- |
| `appointments:read` | Read appointment schedules and availability |
| `appointments:write` | Book or modify patient appointments |
| `doctors:read` | Query medical staff directory and specialties |
| `departments:read` | Query hospital departments and services |

## Token Revocation

Revoke issued tokens by issuing a POST request to `https://shilmoon.hospital/oauth/revoke`.