# Piggy Ledger auth.md

> Autonomous AI Agent Registration & Authentication Protocol Specification for Piggy Ledger (`https://piggyapp.top`).

This document describes how autonomous AI agents, machine clients, and generative agents can discover, register, authenticate, and interact with Piggy Ledger resources per the **Auth.md** specification.

---

## 1. Discovery Metadata

Piggy Ledger publishes RFC-compliant discovery documents for automated authorization:

- **Auth.md Specification Document:** `https://piggyapp.top/auth.md`
- **OAuth 2.0 Protected Resource Metadata (PRM):** `https://piggyapp.top/.well-known/oauth-protected-resource`
- **OAuth 2.0 Authorization Server Metadata (RFC 8414):** `https://piggyapp.top/.well-known/oauth-authorization-server`
- **OpenID Connect Configuration:** `https://piggyapp.top/.well-known/openid-configuration`
- **RFC 9727 API Catalog:** `https://piggyapp.top/.well-known/api-catalog`
- **OpenAPI 3.0 Specification:** `https://piggyapp.top/openapi.json`

---

## 2. Protected Resource Metadata (PRM)

- **Resource Identifier:** `https://piggyapp.top/`
- **Authorization Server Issuer:** `https://piggyapp.top`
- **Supported Bearer Methods:** `header` (`Authorization: Bearer <token>`)
- **Supported Scopes:**
  - `read`: Read-only access to public budgets, categories, and rates
  - `write`: Create and manage budget records and expense envelopes
  - `offline_access`: Issue refresh tokens for continuous agent assistance

---

## 3. Agent Registration Methods

Piggy Ledger supports multiple onboarding pathways for AI agents:

### Method A: Anonymous Agent Registration (Zero Friction)
Agents requiring public ledger inspection, currency conversions, or budget calculations can register anonymously without credentials.

- **Registration Endpoint:** `https://piggyapp.top/oauth/register`
- **Supported Identity Types:** `anonymous`
- **Credential Types Supported:** `api_key`, `ephemeral_bearer`
- **Registration Flow:**
  ```http
  POST /oauth/register HTTP/1.1
  Host: piggyapp.top
  Content-Type: application/json

  {
    "client_name": "MyPersonalAgent",
    "grant_types": ["client_credentials"],
    "identity_type": "anonymous"
  }
  ```
- **Response:**
  ```json
  {
    "client_id": "agent_anon_4e347d83",
    "client_secret": "sec_piggy_ephemeral_token",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "read"
  }
  ```

### Method B: Verified Email Registration
For agents representing human users who require encrypted synchronization across devices.

- **Identity Types Supported:** `identity_assertion`
- **Assertion Types Supported:** `verified_email`
- **Claim URI:** `https://piggyapp.top/oauth/register`
- **Credential Types:** `client_secret_post`, `bearer_token`

### Method C: Identity Assertion (ID-JAG)
- **Identity Types Supported:** `identity_assertion`
- **Assertion Types Supported:** `urn:ietf:params:oauth:token-type:id-jag`
- **Revocation URI:** `https://piggyapp.top/oauth/revoke`
- **Events Supported:** `urn:ietf:params:oauth:event:token-revoked`

---

## 4. Token Usage & Authorization

Authorized requests must supply the bearer token in standard HTTP headers:

```http
GET /api/health HTTP/1.1
Host: piggyapp.top
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Accept: application/json
```

---

## 5. Agent Guidelines & Audience

- **Target Audience:** Personal financial assistants, local on-device agents, budget automation bots, and data aggregation agents.
- **Privacy Guarantees:** Piggy Ledger never requires bank credentials or open-banking passwords. All SMS processing is strictly local (on-device).
- **Rate Limits:** Anonymous agents are rate-limited to 60 requests per minute. Verified agents receive high-throughput allowances.
- **Contact:** `contact@piggyapp.top`