# Randevuo auth.md — Agent Registration & Authentication

Welcome to the AI Agent Authentication guide for **Randevuo** (Salon & Barber SaaS Platform).
This document provides complete instructions for autonomous AI agents, assistants, and
integrations to discover, register, and authenticate with the Randevuo REST API.

---

## 1. Audience

This specification is intended for autonomous AI agents, multi-agent frameworks, background
workers, and developer integrations requesting programmatically authorized access to
Randevuo tenant resources (appointments, services, customers, availability, and messaging).

---

## 2. Discovery Documents

Randevuo publishes machine-readable discovery metadata conforming to RFC 9728, RFC 8414,
RFC 9727, and the Auth.md specification:

- **OAuth Protected Resource Metadata (RFC 9728):**
  [https://randevuo.com.tr/.well-known/oauth-protected-resource](https://randevuo.com.tr/.well-known/oauth-protected-resource)
- **OAuth Authorization Server Metadata (RFC 8414 & Auth.md):**
  [https://randevuo.com.tr/.well-known/oauth-authorization-server](https://randevuo.com.tr/.well-known/oauth-authorization-server)
- **API Catalog (RFC 9727):**
  [https://randevuo.com.tr/.well-known/api-catalog](https://randevuo.com.tr/.well-known/api-catalog)
- **OpenAPI 3.0 Specification:**
  [https://randevuo.com.tr/openapi.yaml](https://randevuo.com.tr/openapi.yaml)
- **LLM Context & System Summary:**
  [https://randevuo.com.tr/llms.txt](https://randevuo.com.tr/llms.txt)

---

## 3. Supported Registration & Identity Flows

Randevuo supports programmatic agent onboarding via the `agent_auth` protocol metadata:

### Flow A: Identity Assertion (ID-JAG)
- **Identity Type:** `identity_assertion`
- **Assertion Type:** `urn:ietf:params:oauth:token-type:id-jag`
- **Registration Endpoint:** `POST https://randevuo.com.tr/api/agent/register`
- **Claim Endpoint:** `POST https://randevuo.com.tr/api/agent/claim`
- **Revocation Endpoint:** `POST https://randevuo.com.tr/api/agent/revoke`
- **Credential Types:** `bearer_token`, `api_key`

Agents present an Identity Assertion JWT signed by a trusted identity authority.
Upon verification, the agent receives an access token or scoped API key.

### Flow B: Verified Email
- **Identity Type:** `identity_assertion`
- **Assertion Type:** `verified_email`
- **Claim Endpoint:** `POST https://randevuo.com.tr/api/agent/claim`
- **Credential Types:** `bearer_token`, `api_key`

Agents initiate on behalf of a salon owner or staff member using a verified email challenge.

### Flow C: Anonymous Registration
- **Identity Type:** `anonymous`
- **Claim Endpoint:** `POST https://randevuo.com.tr/api/agent/claim`
- **Credential Types:** `bearer_token`, `api_key`

Agents provision a sandbox or temporary unprivileged key, which can later be claimed and
bound to a tenant by the salon owner via the claim URL.

---

## 4. Supported Scopes

- `appointments:read` — Query salon appointments and schedule slots
- `appointments:write` — Book, reschedule, or cancel salon appointments
- `customers:read` — Access salon customer profiles and booking history
- `customers:write` — Create or update customer contact details
- `services:read` — List salon service catalog, pricing, and durations
- `dm:analyze` — Analyze customer messages from messaging channels (WhatsApp/Instagram)
- `dm:feedback` — Provide response corrections and conversation feedback
- `dm:delivery` — Dispatch customer confirmation messages

---

## 5. Credential Usage

All authenticated API requests must include credentials using HTTP Bearer authorization:

```http
GET /api/public/services HTTP/1.1
Host: randevuo.com.tr
Authorization: Bearer <access_token_or_api_key>
Accept: application/json
```

- **Token Endpoint:** `https://randevuo.com.tr/api/auth/token`
- **Token Auth Methods Supported:** `client_secret_basic`, `client_secret_post`, `none`
- **Grant Types:** `authorization_code`, `client_credentials`, `urn:ietf:params:oauth:grant-type:token-exchange`