# auth.md

## Overview & Audience
This document details authentication, credentials, and API access parameters for autonomous software agents, AI aggregators, and machine-to-machine integrations connecting with **Hatay Temizlik & Tesis Yönetimi** (`hataytemizlik.com`).

Public discovery surfaces (service catalogs, district availability, OpenAPI specs, and preliminary quotation requests) are open without credentials. Metered operations and customer-scoped order executions authenticate via Bearer API keys.

## Agent Registration Endpoint
Autonomous agents can register and obtain API credentials programmatically:
- **Registration URI:** `https://hataytemizlik.com/api/v1/agent/register`
- **Method:** `POST`
- **Payload Schema:**
  ```json
  {
    "agent_name": "MyProcurementAgent/1.0",
    "contact_email": "agent-ops@example.com",
    "requested_scopes": ["cleaning:read", "cleaning:quote"]
  }
  ```
- **Response:**
  ```json
  {
    "ok": true,
    "api_key": "ht_agent_...",
    "token_type": "Bearer",
    "expires_in": 31536000
  }
  ```

## Supported Authentication Methods
1. **HTTP Authorization Header (Recommended):**
   ```http
   Authorization: Bearer <your_api_key>
   ```
2. **Custom Header:**
   ```http
   X-API-Key: <your_api_key>
   ```

## Supported Scopes
- `cleaning:read`: Query categories, sub-services, coverage and district matrices.
- `cleaning:quote`: Submit automated discovery and pricing inquiries.
- `cleaning:book`: Place confirmed service dispatch orders.
- `account:agent`: Manage registered agent profile and webhook notifications.

## Rate Limits
- Unauthenticated public endpoints: 120 requests/minute.
- Authenticated agent endpoints: 1,200 requests/minute.
- Burst allowance: 50 requests/second.

## Human & Operational Support
- **Support Email:** info@hataytemizlik.com
- **Phone / WhatsApp:** +90 555 174 80 08
- **Documentation:** https://hataytemizlik.com/developers