# Auth.md - Agent Authentication Specification

This document provides instructions for AI agents and autonomous systems to authenticate and interact with the **AlgoBoost API**.

---

## 1. Overview

- **Service Name**: AlgoBoost AI Tools Directory
- **Issuer**: \`https://algoboost.algeris.com\`
- **API Base URL**: \`https://algoboost.algeris.com/api/v1\`
- **Auth Discovery**: \`https://algoboost.algeris.com/.well-known/oauth-authorization-server\`
- **Protected Resource**: \`https://algoboost.algeris.com/.well-known/oauth-protected-resource\`
- **Supported Identity Types**: \`did\`, \`agent_id\`, \`email\`
- **Supported Credential Types**: \`api_key\`, \`bearer_token\`, \`jwt\`

---

## 2. Agent Registration

AI agents can register automatically to receive an API Key / Client Credentials:

### Endpoint:
\`POST https://algoboost.algeris.com/api/auth/register\`

### Request Headers:
\`\`\`http
Content-Type: application/json
\`\`\`

### Request Body:
\`\`\`json
{
  "agent_name": "Claude-Explorer/1.0",
  "identity_type": "agent_id",
  "identity_value": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "contact_email": "agent-ops@example.com",
  "requested_scopes": ["tools:read", "categories:read"]
}
\`\`\`

### Response:
\`\`\`json
{
  "status": "success",
  "client_id": "agent_cl_98321048",
  "api_key": "algo_live_ak_demo_agent_key_2026",
  "scopes": ["tools:read", "categories:read"],
  "rate_limit": {
    "requests_per_minute": 120,
    "burst": 300
  },
  "created_at": "2026-08-05T15:00:00Z"
}
\`\`\`

---

## 3. Authenticated Requests

Include the API Key or Bearer Token in the \`Authorization\` header of every API request:

\`\`\`http
GET /api/v1/tools?query=coding HTTP/1.1
Host: algoboost.algeris.com
Authorization: Bearer algo_live_ak_demo_agent_key_2026
Accept: application/json
\`\`\`

Public endpoints (such as \`GET /api/v1/tools\`, \`GET /api/v1/categories\`, \`GET /api/health\`) also support unauthenticated read access with baseline rate limits.

---

## 4. Available Scopes

| Scope | Description |
| :--- | :--- |
| \`tools:read\` | Search, retrieve, and filter AI tools from the directory |
| \`tools:write\` | Submit new AI tools or request data updates |
| \`categories:read\` | List categories and tool taxonomy |
| \`bookmarks:read\` | Retrieve saved tool collections |
| \`bookmarks:write\` | Save or update tool collections |

---

## 5. Token Revocation & Rotation

### Endpoint:
\`POST https://algoboost.algeris.com/api/auth/revoke\`

### Request:
\`\`\`json
{
  "token": "algo_live_ak_demo_agent_key_2026",
  "token_type_hint": "api_key"
}
\`\`\`

---

## 6. Rate Limiting & Error Codes

- **Rate Limit Headers**:
  - \`X-RateLimit-Limit\`: Maximum allowed requests per window
  - \`X-RateLimit-Remaining\`: Remaining requests in current window
  - \`X-RateLimit-Reset\`: UTC epoch seconds when window resets
- **401 Unauthorized**: Missing or invalid Authorization header
- **429 Too Many Requests**: Rate limit exceeded; back off according to \`Retry-After\` header