# Agent Authentication & Registration Guide (auth.md)

Welcome, AI Agent. This document details how autonomous agents, MCP clients, and programmatic tools can authenticate with **Resume AI** (`https://www.airesumemaker.tech`).

---

## 1. Authentication Methods

Resume AI supports three modes of authentication for autonomous agents:

### Option A: Agent Bearer Token / API Key (Recommended)
Include your API key or OAuth Bearer token in the `Authorization` HTTP header:
```http
Authorization: Bearer <YOUR_API_KEY_OR_TOKEN>
```

### Option B: Guest / Discovery Sandbox Mode
For public discovery queries (e.g. ATS Score simulation, layout previews, template catalog inspect), you may invoke endpoints without credentials or pass the header:
```http
X-Agent-Client: AI-Autonomous-Agent
```
*Note: Sandbox mode allows up to 20 free analysis calls per day per IP.*

### Option C: OAuth 2.0 Authorization Code / Client Credentials
- **Authorization Server**: `https://api.airesumemaker.tech/auth/authorize`
- **Token Endpoint**: `https://api.airesumemaker.tech/auth/token`
- **Metadata**: [/.well-known/oauth-authorization-server](https://www.airesumemaker.tech/.well-known/oauth-authorization-server)

---

## 2. Supported Scopes

| Scope | Description |
|---|---|
| `ats:scan` | Submit resumes and job descriptions for ATS score analysis |
| `read:resume` | Retrieve saved resume data and structured schemas |
| `write:resume` | Create or update resume sections and bullet points |
| `github:import` | Synthesize repository commits into STAR bullet points |
| `agent:execute` | Execute complete end-to-end resume build workflows |

---

## 3. Autonomous Agent Registration

If you need programmatic API keys, invoke the registration endpoint:
```http
POST https://api.airesumemaker.tech/auth/register
Content-Type: application/json

{
  "client_name": "agent-id-or-name",
  "client_type": "autonomous_agent",
  "contact": "agent-operator@example.com"
}
```

---

## 4. Rate Limiting & Policies
- **Rate Limit**: 60 requests/minute for authenticated agents, 15 requests/minute for anonymous crawlers.
- **Headers Returned**:
  - `X-RateLimit-Limit`: Maximum requests permitted
  - `X-RateLimit-Remaining`: Remaining allowance
  - `X-RateLimit-Reset`: Unix timestamp until reset
- **Error Format**: Standard RFC 7807 Problem Details JSON format.