# auth.md

## Autonomous AI Agent Registration & Authentication

> **Service:** ToolsWallet  
> **Service Root:** https://toolswallet.dev  
> **Target Audience:** Autonomous AI Agents, LLM Crawlers, Multi-Agent Orchestrators, and Developers  
> **Specification:** Auth.md Agent Registration & RFC 9728 / RFC 8414 OAuth Discovery

---

## 1. Agent Audience & Overview

ToolsWallet provides 40+ free, client-side, privacy-first developer, PDF, image, and AI utilities. AI agents and autonomous bots can discover, register, and interact with the service programmatically.

---

## 2. Agent Registration Flow & Provisioning Endpoints

Agents can register and provision credentials using the following standardized endpoints:

- **Registration Endpoint:** `https://toolswallet.dev/oauth/register`
- **Claim Endpoint:** `https://toolswallet.dev/oauth/claim`
- **Token Endpoint:** `https://toolswallet.dev/oauth/token`

### Supported Identity Types
1. **`anonymous`** — Instant provisioning for zero-friction client-side utility calls.
2. **`identity_assertion`** — Federated authentication supporting:
   - `verified_email`
   - `urn:ietf:params:oauth:token-type:id-jag` (ID-JAG assertions)

### Supported Credential Types
- `bearer_token`
- `api_key`

---

## 3. Step-by-Step Registration Instructions for Agents

### Step 1: Request Registration / Provisioning
Agents send an HTTP POST request to the registration URI:

```http
POST /oauth/register HTTP/1.1
Host: toolswallet.dev
Content-Type: application/json

{
  "identity_type": "anonymous"
}
```

Or with email verification:

```http
POST /oauth/register HTTP/1.1
Host: toolswallet.dev
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion_type": "verified_email",
  "email": "agent@example.com"
}
```

### Step 2: Claim Token & Credentials
The registration response returns provisioning details and a claim URI:

```http
POST /oauth/claim HTTP/1.1
Host: toolswallet.dev
Content-Type: application/json

{
  "claim_id": "<claim_id_from_step_1>"
}
```

### Step 3: Credential Usage in Tool Invocations
Send the acquired credential via standard HTTP Authorization header:

```http
GET /api/mcp HTTP/1.1
Host: toolswallet.dev
Authorization: Bearer <your_bearer_token>
```

---

## 4. Machine-Readable OAuth Metadata

- **OAuth Protected Resource Metadata (PRM):**  
  `https://toolswallet.dev/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata:**  
  `https://toolswallet.dev/.well-known/oauth-authorization-server`
- **Agent Skills Index:**  
  `https://toolswallet.dev/.well-known/agent-skills/index.json`
- **A2A Agent Card:**  
  `https://toolswallet.dev/.well-known/agent-card.json`
- **MCP Server Card:**  
  `https://toolswallet.dev/.well-known/mcp/server-card.json`
- **API Catalog:**  
  `https://toolswallet.dev/.well-known/api-catalog`
- **Web Bot Auth JWKS:**  
  `https://toolswallet.dev/.well-known/http-message-signatures-directory`

---

## 5. Public Utilities (Zero-Auth Access)

All 40+ browser tools (PDF Merger, Image Compressor, JSON Formatter, QR Generator, Video to MP3, etc.) run locally in-browser or on public endpoints with no authentication barrier.

---

## 6. Rate Limits & Headers

- **Rate Limits:** < 30 requests/second per IP.
- **Bot Identification:** Please provide standard `User-Agent` (e.g. `GPTBot`, `ClaudeBot`, `PerplexityBot`, `ToolsWalletAgent/1.0`).
- **Signature Headers:** Signed requests must include `Signature-Agent` and `Signature-Input` headers per WebBotAuth.