# auth.md - Azara AI Agent Registration Specification

Agent Authentication and Registration Specification for Azara AI (`https://azaraai.app`).

## Overview
Azara AI provides programmatic and automated interfaces for AI agents, developers, and autonomous evaluators interacting with interview preparation, live assessment simulations, and resume synthesis services.

## Discovery Endpoints
- **OAuth Protected Resource Metadata (RFC 9728)**: `https://azaraai.app/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414)**: `https://azaraai.app/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery**: `https://azaraai.app/.well-known/openid-configuration`
- **API Catalog (RFC 9727)**: `https://azaraai.app/.well-known/api-catalog`
- **MCP Server Card (SEP-1649)**: `https://azaraai.app/.well-known/mcp/server-card.json`
- **Agent Skills Index**: `https://azaraai.app/.well-known/agent-skills/index.json`
- **ARD Capability Manifest**: `https://azaraai.app/.well-known/ai-catalog.json`

## Agent Registration & Provisioning Instructions

Agents can register and obtain credentials through one of three automated flows:

### 1. Identity Assertion (ID-JAG / Verified Email)
- **Assertion Types**: `urn:ietf:params:oauth:token-type:id-jag`, `verified_email`
- **Claim Endpoint**: `POST https://azaraai.app/auth/claim`
- **Revocation Endpoint**: `POST https://azaraai.app/auth/revoke`
- **Supported Credentials**: `bearer_jwt`, `api_key`

To claim credentials via signed identity assertion:
```http
POST /auth/claim HTTP/1.1
Host: azaraai.app
Content-Type: application/json

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id-jag",
  "subject_token": "<signed_identity_assertion_jwt>",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

### 2. Anonymous Trial Sessions
- **Credential Type**: `anonymous_session`
- **Claim Endpoint**: `POST https://azaraai.app/auth/claim`

```http
POST /auth/claim HTTP/1.1
Host: azaraai.app
Content-Type: application/json

{
  "identity_type": "anonymous",
  "client_name": "Autonomous-Evaluation-Agent"
}
```

### 3. Developer Portal Interactive Registration
Developers and agent operators can generate persistent M2M API keys via the interactive developer dashboard at `https://azaraai.app/developers` or `https://azaraai.app/dashboard/settings`.

## Supported Authentication Methods

### 1. Bearer Token (JWT)
Protected endpoints accept standard Bearer authorization headers:
```http
Authorization: Bearer <user_or_agent_jwt>
```

### 2. API Key
Agents registered with machine-to-machine credentials can authenticate with `X-API-Key`:
```http
X-API-Key: az_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

### 3. Anonymous Session Tokens
For passive evaluation and trial assessments, anonymous sessions are supported via ephemeral session tokens issued at `https://azaraai.app/auth/claim`.

## Scopes Supported
- `openid`: Standard OpenID profile access
- `profile`: User and organization profile metadata
- `email`: Account email address
- `interview:read`: Retrieve interview transcripts and analysis
- `interview:write`: Submit prompt questions and real-time audio streams
- `teleprompter:stream`: Stream real-time synthesized teleprompter responses

## Rate Limits
- Standard authenticated tier: 120 requests/minute
- Machine-to-machine streaming tier: 600 requests/minute
- Public discovery endpoints: Uncapped with CDN caching

## DNS for AI Discovery (DNS-AID)
Azara advertises decentralized discovery endpoints under the `_agents` DNS namespace per RFC 9460 & `draft-mozleywilliams-dnsop-dnsaid`:
```dns
_index._agents.azaraai.app. 3600 IN SVCB  1 azaraai.app. alpn="a2a,h2,h3" port=443 mandatory=alpn,port
_index._agents.azaraai.app. 3600 IN HTTPS 1 azaraai.app. alpn="h2,h3" port=443 mandatory=alpn,port
_a2a._agents.azaraai.app.   3600 IN SVCB  1 azaraai.app. alpn="a2a" port=443 mandatory=alpn,port
_mcp._agents.azaraai.app.   3600 IN SVCB  1 azaraai.app. alpn="mcp,h2,h3" port=443 mandatory=alpn,port
_http._agents.azaraai.app.  3600 IN HTTPS 1 azaraai.app. alpn="h2,h3" port=443 mandatory=alpn,port
```
Discovery zones are cryptographically signed with DNSSEC (Algorithm 13 ECDSAP256SHA256) so validating resolvers return authenticated data (AD: true).