# Auth.md - Agent Authentication Specification

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

---

## 1. Overview

- **Service Name**: Nodal AI Tools Directory
- **Issuer**: `https://nodal.sonnev.com`
- **API Base URL**: `https://nodal.sonnev.com/api/v1`
- **Auth Discovery**: `https://nodal.sonnev.com/.well-known/oauth-authorization-server`
- **Protected Resource**: `https://nodal.sonnev.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://nodal.sonnev.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": "nodal_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: nodal.sonnev.com
Authorization: Bearer nodal_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://nodal.sonnev.com/api/auth/revoke`

### Request:

```json
{
  "token": "nodal_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
