# Auth.md

Agent registration and authentication protocol for Captain Karim Zakaria Fitness & Nutrition AI Services.

## Overview
This document describes how autonomous AI agents, assistants, and tools discover, register, obtain credentials, and interact with the AI services and tools at `https://karimzakaria.com`.

## Discovery
- **Protected Resource Metadata (PRM)**: `https://karimzakaria.com/.well-known/oauth-protected-resource`
- **Authorization Server**: `https://karimzakaria.com/.well-known/oauth-authorization-server`
- **Agent Auth Registration**: `https://karimzakaria.com/auth.md`
- **MCP Server Card**: `https://karimzakaria.com/.well-known/mcp/server-card.json`
- **Agent Skills**: `https://karimzakaria.com/.well-known/agent-skills/index.json`
- **API Catalog (RFC 9727)**: `https://karimzakaria.com/.well-known/api-catalog`
- **LLMs Context**: `https://karimzakaria.com/llms.txt`

## Supported Identity & Credential Types
- **Supported Identity Types**: `agent`, `user`
- **Supported Credential Types**: `bearer_token`, `api_key`

## Registration Flows

### 1. Agent Verified Flow (Autonomous)
Agents possessing a valid Identity Assertion (such as ID-JAG or signed JWT) can request scoped credentials directly without user intervention.

```http
POST /api/oauth/token HTTP/1.1
Host: karimzakaria.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "<JWT>",
  "scope": "fitness:read fitness:tools"
}
```

### 2. User Claimed Flow (Interactive / Delegated)
For agents acting on behalf of a specific client or user:
1. Agent directs user to verification / claim URL.
2. User authenticates and authorizes agent permissions.
3. Service issues delegated access token to the agent.

<a name="claim"></a>
- **Claim URL**: `https://karimzakaria.com/auth.md#claim`

### 3. Public Read-Only Access
Public fitness calculation tools and package metadata do not require pre-registration or authentication tokens:
- **Calorie & Macro Calculator**: `https://karimzakaria.com/api/skills/calculator.json`
- **Coaching Packages**: `https://karimzakaria.com/api/skills/packages.json`

## Token Usage
Include the issued token in the `Authorization` header for protected endpoints:
```http
Authorization: Bearer <access_token>
```

## Revocation & Audit
Tokens can be revoked at any time by the agent or user via:
- **Revocation URL**: `https://karimzakaria.com/api/oauth/revoke`

```http
POST /api/oauth/revoke HTTP/1.1
Host: karimzakaria.com
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token
```

## Contact & Support
- Website: [https://karimzakaria.com](https://karimzakaria.com)
- WhatsApp: [+201062024767](https://wa.me/201062024767)