# auth.md

> Version: 1.0.0  
> Base URL: `https://api.ai-reception.ist`  
> Issuer: `https://ai-reception.ist`  
> Authorization Metadata: `https://ai-reception.ist/.well-known/oauth-authorization-server`  
> Protected Resource Metadata: `https://ai-reception.ist/.well-known/oauth-protected-resource`

---

## 1. Overview for Autonomous AI Agents
AI-Reception.ist supports programmatic authentication for autonomous AI agents, multi-agent frameworks (CrewAI, AutoGen, LangGraph, Smolagents), and server-to-server telephony dispatchers.

Agents can authenticate using:
1. **Dynamic Agent Registration**: RFC 7591 dynamic client registration for autonomous software agents.
2. **ID-JAG & Identity Assertion**: WorkOS ID-JAG token assertion and verified email assertions.
3. **OAuth 2.0 Client Credentials**: RFC 6749 machine-to-machine authentication.
4. **Anonymous & API Keys**: For developer sandboxes and instant evaluation.

---

## 2. Dynamic Agent Registration Endpoint
Autonomous agents can register programmatically by posting their public profile and required scopes:

```http
POST /v1/agents/register HTTP/1.1
Host: api.ai-reception.ist
Content-Type: application/json

{
  "client_name": "Autonomous-Medical-Concierge-Agent",
  "client_uri": "https://partner-agent.example.com",
  "grant_types": ["client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange"],
  "scope": "calls:read calls:write appointments:sync",
  "identity_type": "agent"
}
```

### Response:
```json
{
  "client_id": "agent_live_9f81a7b64c21",
  "client_secret": "sec_live_948f2190dbac4710",
  "client_id_issued_at": 1787498000,
  "client_secret_expires_at": 0,
  "token_endpoint": "https://ai-reception.ist/api/auth/token",
  "token_type": "Bearer"
}
```

---

## 3. Obtaining Access Tokens (Client Credentials Grant)

```http
POST /api/auth/token HTTP/1.1
Host: ai-reception.ist
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=agent_live_9f81a7b64c21&client_secret=sec_live_948f2190dbac4710&scope=calls:read%20calls:write
```

### Response:
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "calls:read calls:write"
}
```

---

## 4. Supported Scopes & Permissions

| Scope | Description |
| :--- | :--- |
| `calls:read` | Read call logs, sentiment analysis, audio waveforms, and transcripts. |
| `calls:write` | Initiate inbound/outbound telephony sessions and SIP trunks. |
| `agents:manage` | Create, configure, update, and deploy AI receptionist voice personas. |
| `telephony:route` | Update phone number routing tables and SIP forwarding endpoints. |
| `appointments:sync` | Bidirectional synchronization with EHR (Epic/Cerner) and CRM calendars. |
| `analytics:view` | Retrieve call volume statistics, latency metrics, and ROI telemetry. |

---

## 5. Token Revocation
To invalidate an agent credential:
```http
POST /v1/auth/revoke HTTP/1.1
Host: api.ai-reception.ist
Content-Type: application/x-www-form-urlencoded

token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&token_type_hint=access_token
```

---

## 6. Security & Rate Limiting
- **Rate Limit**: 1,000 API calls per minute per agent credential.
- **Transport**: Strict TLS 1.3 encryption required.
- **Audit Logging**: Every token generation and API invocation is signed and immutably recorded for HIPAA/SOC2 compliance.