# auth.md

> **Audience:** AI agents, automated clients, and developers interacting with Toolminex services, tools, and APIs.

This document is the canonical registration and authentication manifest for Toolminex's agent discovery and execution protocol, per the [Auth.md specification](https://github.com/workos/auth.md).

---

## Service Information

| Field | Value |
|-------|-------|
| **Name** | Toolminex |
| **Product** | Fast, Private, Free Online Developer & Productivity Tools |
| **Website** | https://toolminex.com |
| **Contact Email** | info@codeminex.com |
| **Auth Metadata** | https://toolminex.com/.well-known/oauth-authorization-server |
| **OpenID Configuration** | https://toolminex.com/.well-known/openid-configuration |
| **Protected Resource** | https://toolminex.com/.well-known/oauth-protected-resource |
| **MCP Server Card** | https://toolminex.com/.well-known/mcp/server-card.json |
| **API Catalog** | https://toolminex.com/.well-known/api-catalog |
| **A2A Agent Card** | https://toolminex.com/.well-known/agent-card.json |

---

## Public Endpoints — No Credentials Required

These endpoints are open to all AI agents, web crawlers, and automated assistants without authentication:

| Method | Endpoint | Content-Type | Description |
|--------|----------|--------------|-------------|
| GET | `/api/content` | `text/markdown` | Full tools catalog and capability overview |
| GET | `/.well-known/api-catalog` | `application/linkset+json` | RFC 9727 API catalog of published tool interfaces |
| GET | `/.well-known/agent-card.json` | `application/json` | A2A protocol agent discovery card |
| GET | `/.well-known/mcp/server-card.json` | `application/json` | SEP-1649 Model Context Protocol server card |
| POST | `/api/mcp` | `application/json` | Streamable HTTP JSON-RPC 2.0 MCP interface |
| GET | `/.well-known/ai-catalog.json` | `application/json` | ARD AI catalog registry document |
| GET | `/.well-known/agent-skills/index.json` | `application/json` | Agent skills discovery manifest |
| GET | `/api/health` | `application/json` | Health status and availability check |
| GET | `/api/ip-address` | `application/json` | IP address detection API |
| POST | `/api/dns-lookup` | `application/json` | DNS record lookup API |
| POST | `/api/ssl-checker` | `application/json` | SSL certificate inspection API |

---

## Agent Registration — Anonymous Flow

Toolminex supports an **anonymous registration method** for AI agents. No preexisting human user account or OAuth redirect is necessary. Upon review or automated provisioning of the agent registration request, Toolminex issues a long-lived **Bearer token** (API key).

### Step 1 — Discovery

Discover the authorization server metadata:

```http
GET /.well-known/oauth-authorization-server HTTP/1.1
Host: toolminex.com
Accept: application/json
```

The metadata document provides the `agent_auth` configuration block:

```json
{
  "skill": "https://toolminex.com/auth.md",
  "register_uri": "https://toolminex.com/contact",
  "claim_uri": "https://toolminex.com/contact",
  "revocation_uri": "https://toolminex.com/contact",
  "identity_types_supported": ["anonymous"],
  "anonymous": {
    "credential_types_supported": ["bearer-token"]
  },
  "scopes_supported": [
    "tools:read",
    "tools:execute",
    "content:read",
    "catalog:read"
  ]
}
```

### Step 2 — Register

Submit an agent registration request to the `register_uri`:

- **Web Endpoint:** `https://toolminex.com/contact`
- **Email:** `info@codeminex.com`
- **API POST:** `POST /api/contact`

Include the following parameters:

```yaml
agent_name: <Your Agent or Assistant Name>
agent_version: <Version, e.g. 1.0.0>
intended_use: <Summary of agent tasks, e.g. tool execution, automated formatting, data conversion>
contact_email: <Developer or Operator Email>
requested_scopes:
  - tools:read
  - tools:execute
  - content:read
```

### Step 3 — Claim Token

Once approved, a **Bearer token** is returned via email or API response from the `claim_uri`.

### Step 4 — Authenticate Requests

Include the Bearer token in the `Authorization` header of API requests:

```http
POST /api/mcp HTTP/1.1
Host: toolminex.com
Authorization: Bearer <your-bearer-token>
Content-Type: application/json

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
```

Supported credential type: `bearer-token` (HTTP Authorization header format: `Bearer <token>`).

### Step 5 — Revocation

To revoke or rotate an active token:

- Contact: `info@codeminex.com` or `https://toolminex.com/contact`
- Message: `Token Revocation Request: <first-8-chars-of-token>`

---

## Supported Scopes

| Scope | Description |
|-------|-------------|
| `tools:read` | Read tool documentation, parameter schemas, and execution requirements |
| `tools:execute` | Execute backend utility tools via REST APIs and MCP endpoint |
| `content:read` | Retrieve full tools catalog, markdown representations, and guides |
| `catalog:read` | Read RFC 9727 API catalog, A2A agent cards, and MCP discovery feeds |

---

## Rate Limits

| Tier | Requests / Minute | Burst Limit |
|------|-------------------|-------------|
| Public (Unauthenticated) | 60 | 100 |
| Registered AI Agent | 300 | 500 |
| Verified Partner | Custom | Custom |

---

## DNS for AI Discovery (DNS-AID) Records

For DNS-based agent discovery per [draft-mozleywilliams-dnsop-dnsaid](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/) and [RFC 9460](https://www.rfc-editor.org/rfc/rfc9460):

```dns
_index._agents.toolminex.com. 3600 IN SVCB 1 toolminex.com. alpn="h2,h3" port=443 mandatory=alpn,port
_a2a._agents.toolminex.com. 3600 IN SVCB 1 toolminex.com. alpn="a2a" port=443 mandatory=alpn,port
```

---

## Canonical Links & Discovery Documents

- [OAuth Authorization Server](https://toolminex.com/.well-known/oauth-authorization-server)
- [OpenID Configuration](https://toolminex.com/.well-known/openid-configuration)
- [OAuth Protected Resource](https://toolminex.com/.well-known/oauth-protected-resource)
- [MCP Server Card](https://toolminex.com/.well-known/mcp/server-card.json)
- [RFC 9727 API Catalog](https://toolminex.com/.well-known/api-catalog)
- [A2A Agent Card](https://toolminex.com/.well-known/agent-card.json)
- [Agent Skills Discovery Index](https://toolminex.com/.well-known/agent-skills/index.json)
- [ARD AI Catalog](https://toolminex.com/.well-known/ai-catalog.json)
- [Privacy Policy](https://toolminex.com/privacy-policy)
- [Terms of Service](https://toolminex.com/terms)