# Mockya auth.md

This document defines agent authentication and registration protocols for autonomous AI agents interacting with Mockya APIs and services.

## Audience

This specification is intended for AI agents, LLM assistants, and automated workflows requesting programmatic access to Mockya's video rendering and export APIs.

## Discovery Metadata

Mockya publishes standardized discovery metadata:

- **OAuth Protected Resource Metadata (RFC 9728):** [`/.well-known/oauth-protected-resource`](https://mockya.app/.well-known/oauth-protected-resource)
- **OAuth Authorization Server Metadata (RFC 8414):** [`/.well-known/oauth-authorization-server`](https://mockya.app/.well-known/oauth-authorization-server)
- **OpenID Connect Discovery:** [`/.well-known/openid-configuration`](https://mockya.app/.well-known/openid-configuration)
- **API Catalog (RFC 9727):** [`/.well-known/api-catalog`](https://mockya.app/.well-known/api-catalog)

## Registration Endpoints

Agents may register, claim, or revoke credentials via the following endpoints:

- **Registration URI:** `https://mockya.app/api/agent/register`
- **Claim URI:** `https://mockya.app/api/agent/claim`
- **Revocation URI:** `https://mockya.app/api/agent/revoke`
- **Token Endpoint:** `https://mockya.app/api/auth/token`

## Agent Auth Configuration

```json
{
  "skill": "https://mockya.app/auth.md",
  "auth_md": "https://mockya.app/auth.md",
  "register_uri": "https://mockya.app/api/agent/register",
  "claim_uri": "https://mockya.app/api/agent/claim",
  "revocation_uri": "https://mockya.app/api/agent/revoke",
  "events_supported": [
    "https://schemas.auth.md/events/revocation"
  ],
  "identity_types_supported": [
    "anonymous",
    "identity_assertion"
  ],
  "anonymous": {
    "credential_types_supported": [
      "api_key"
    ],
    "claim_uri": "https://mockya.app/api/agent/claim"
  },
  "identity_assertion": {
    "assertion_types_supported": [
      "urn:ietf:params:oauth:token-type:id-jag",
      "verified_email"
    ],
    "credential_types_supported": [
      "bearer_token"
    ],
    "claim_uri": "https://mockya.app/api/agent/claim",
    "revocation_uri": "https://mockya.app/api/agent/revoke"
  }
}
```

## Supported Identity & Credential Types

### 1. Anonymous Agent Provisioning
- **Identity Type:** `anonymous`
- **Credential Type:** `api_key`
- **Provisioning Flow:** POST to `https://mockya.app/api/agent/register` with `{ "type": "anonymous" }`.
- **Usage:** Pass the issued API key in the `Authorization: Bearer <api_key>` header on subsequent API requests.

### 2. Identity Assertion (ID-JAG / Verified Email)
- **Identity Type:** `identity_assertion`
- **Assertion Types Supported:**
  - `urn:ietf:params:oauth:token-type:id-jag`
  - `verified_email`
- **Credential Type:** `bearer_token`
- **Flow:** Present a signed identity token to `https://mockya.app/api/auth/token` via OAuth 2.0 token exchange (`urn:ietf:params:oauth:grant-type:token-exchange`).

## Supported Scopes

- `credits:read` — View current export credit balance and transaction history.
- `credits:deduct` — Deduct credits for a completed rendering task.
- `user:profile` — Retrieve account metadata and preferences.

## Resource Protection

All protected API endpoints require HTTP Authorization headers:
```http
Authorization: Bearer <access_token_or_api_key>
```
Unauthenticated requests will receive HTTP 401 with `WWW-Authenticate: Bearer realm="mockya", resource_metadata="https://mockya.app/.well-known/oauth-protected-resource"`.