# Agent Authentication & Integration Guide (Auth.md)

This document describes how autonomous AI agents, automated systems, and delegating assistants authenticate and interact with Zuxxis APIs and services.

## Identification & User-Agent
Autonomous agents interacting with Zuxxis (https://zuxxis.in) should identify themselves by including an informative `User-Agent` header containing:
- Agent or system name
- Purpose or operator contact (URL or email)

Example:
```http
User-Agent: ResearchAgent/1.0 (+https://example.com/bot; bot@example.com)
```

## Public Endpoints (No Auth Required)
The following resources are publicly accessible without authentication tokens:
- **LLM Context Document**: `https://zuxxis.in/llms.txt`
- **Agentic Resource Discovery (ARD)**: `https://zuxxis.in/.well-known/ai-catalog.json`
- **API Catalog**: `https://zuxxis.in/.well-known/api-catalog`
- **MCP Server Card**: `https://zuxxis.in/.well-known/mcp/server-card.json`
- **Agent Skills**: `https://zuxxis.in/.well-known/agent-skills/index.json`
- **Consultation & Project Inquiry**: `POST https://api.zuxxis.in/api/inquiry`

## Authenticated API Access
For high-volume, automated agent integrations or client dashboard access:
1. **OAuth 2.0 Authorization Server**: Discover server endpoints at `https://zuxxis.in/.well-known/oauth-authorization-server`.
2. **OpenID Connect**: Discover OIDC metadata at `https://zuxxis.in/.well-known/openid-configuration`.
3. **Protected Resources**: Defined in `https://zuxxis.in/.well-known/oauth-protected-resource`.

### Obtaining Access Tokens
AI agents can exchange authorized credentials via the token endpoint:
```http
POST https://auth.zuxxis.in/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&scope=inquiry:write+project:read
```

### Making Authenticated Requests
Include the bearer token in the HTTP Authorization header:
```http
Authorization: Bearer <access_token>
```

## Rate Limiting & Ethics
- Standard endpoints allow up to 60 requests per minute per IP.
- Please respect caching headers (`Cache-Control`, `ETag`).
- Direct human inquiries to: `reply@zuxxis.in`.