# Natrium auth.md - Autonomous Agent Registration & Authentication

Welcome to the **Natrium Sovereign Communication Platform** agent authentication documentation. This document specifies how autonomous AI agents, MCP (Model Context Protocol) runners, and automated services discover, register, and authenticate to Natrium APIs.

---

## Agent Audience

This documentation is intended for:
- Autonomous AI Agents (e.g. Google DeepMind, OpenAI, Anthropic, LangChain, AutoGPT)
- MCP (Model Context Protocol) Servers and Tool Connectors
- Automated Inbound/Outbound Email Processors
- Security & Content Safety Scanners (PhotoDNA / NCMEC Hash Verification)

---

## Machine-Readable Discovery Endpoints

Natrium publishes standard discovery metadata for automated agents:

- OAuth Protected Resource Metadata: https://natrium.sh/.well-known/oauth-protected-resource
- OAuth Authorization Server Metadata: https://natrium.sh/.well-known/oauth-authorization-server
- RFC 9727 API Catalog: https://natrium.sh/.well-known/api-catalog
- OpenAPI 3.1 Specification: https://natrium.sh/openapi.json
- Platform Health Check: https://natrium.sh/api/health

| Specification | Well-Known Metadata Link | Description |
| :--- | :--- | :--- |
| **OAuth Protected Resource Metadata** | [https://natrium.sh/.well-known/oauth-protected-resource](https://natrium.sh/.well-known/oauth-protected-resource) | RFC 9728 resource metadata declaring authorization servers and scopes |
| **OAuth Authorization Server Metadata** | [https://natrium.sh/.well-known/oauth-authorization-server](https://natrium.sh/.well-known/oauth-authorization-server) | RFC 8414 authorization metadata with `agent_auth` configuration |
| **RFC 9727 API Catalog** | [https://natrium.sh/.well-known/api-catalog](https://natrium.sh/.well-known/api-catalog) | RFC 9727 linkset catalog listing all discoverable APIs |
| **OpenAPI 3.1 Specification** | [https://natrium.sh/openapi.json](https://natrium.sh/openapi.json) | Comprehensive machine-readable API specification |
| **Platform Health Check** | [https://natrium.sh/api/health](https://natrium.sh/api/health) | Real-time liveness and service readiness status |

---

## Supported Registration & Authentication Methods

Natrium supports three primary agent authentication flows:

### 1. ID-JAG Identity Assertion (`urn:ietf:params:oauth:token-type:id-jag`)
Agents holding an identity assertion from an authorized identity provider can exchange their assertion for an agent access token.
- **Assertion Type:** `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types:** `bearer`, `api_key`
- **Registration Endpoint:** `POST https://natrium.sh/api/auth/agent/register`
- **Token Endpoint:** `POST https://natrium.sh/oauth/token`
- **Revocation Endpoint:** `POST https://natrium.sh/api/auth/agent/revoke`
- **Supported Events:** `revocation`

### 2. Verified Email Claim
Agents acting on behalf of a verified human or organization email address can claim credentials using an email challenge loop.
- **Assertion Type:** `verified_email`
- **Credential Types:** `bearer`, `api_key`
- **Claim Endpoint:** `POST https://natrium.sh/api/auth/agent/claim`

### 3. Anonymous / Ephemeral Access
For unauthenticated public services (such as Content Safety hash lookups and system telemetry), agents may acquire ephemeral credentials without permanent account registration.
- **Identity Type:** `anonymous`
- **Credential Types:** `bearer`, `api_key`
- **Claim Endpoint:** `POST https://natrium.sh/api/auth/agent/anonymous`

---

## Scopes & Permissions

Agents can request fine-grained scopes matching their task requirements:

- `mail:read` - Read inbox messages, folders, and metadata
- `mail:send` - Queue and dispatch outbound email messages via Natrium MTA
- `content-safety:verify` - Verify media hashes against PhotoDNA / NCMEC database
- `telemetry:read` - Access public network status and server metrics

---

## Credential Usage

Include credentials in all authenticated requests using standard HTTP headers:

```http
Authorization: Bearer <your_agent_token>
```

Or using an API key header:

```http
x-api-key: <your_api_key>
```