# auth.md

This file describes how AI agents can register and authenticate with aliyev.site.

## Agent Registration

Agents can authenticate with this service using OAuth 2.0 / OpenID Connect or API keys.
Discovery metadata is published at:

- **OAuth Authorization Server**: `/.well-known/oauth-authorization-server`
- **OAuth Protected Resource**: `/.well-known/oauth-protected-resource`

### Register an Agent

To register as an agent (obtain credentials), send a POST request to:

```
https://aliyev.site/auth/register
```

### Supported Identity Types

#### Identity Assertion (`identity_assertion`)

Agents acting on behalf of a verified user may use identity assertions:

- **Assertion types supported**:
  - `urn:ietf:params:oauth:token-type:id-jag` — ID-JAG identity assertion
  - `verified_email` — Verified email claim
- **Credential types**: `bearer`
- **Claim URI**: `https://aliyev.site/auth/register`
- **Revocation URI**: `https://aliyev.site/auth/revoke`

#### Anonymous (`anonymous`)

Agents without a verified user identity may register anonymously:

- **Credential types**: `api_key`, `bearer`
- **Claim URI**: `https://aliyev.site/auth/register`

### Authentication Flow

1. **Discover** authorization server metadata at `/.well-known/oauth-authorization-server`
2. **Register** at `https://aliyev.site/auth/register`
3. **Authorize** at `https://aliyev.site/auth/authorize`
4. **Exchange** for a token at `https://aliyev.site/auth/token`
5. **Use** `Authorization: Bearer <token>` or `X-API-KEY: <key>` header in API requests

### Supported Grant Types

- `authorization_code`
- `client_credentials`
- `api_key`

### Scopes

- `openid`
- `profile`
- `email`
- `search`

### Token Revocation

Revoke tokens at: `https://aliyev.site/auth/revoke`

## Pay-Per-Use HTTP Payments (x402 & L402 Protocol)

Autonomous AI agents can pay per API request directly via HTTP without prior registration or API keys:

- **Paid Endpoint**: `https://aliyev.site/WebMesh/search`
- **Supported Payment Protocols**:
  - **x402 Protocol**: USDC on Base (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) via Coinbase Facilitator (`https://x402.org/facilitator`).
  - **L402 Protocol**: Bitcoin Lightning Network via LNURL-pay.
- **Pricing**:
  - Basic Web Search: `$0.01` (10,000 USDC units / 10 sats)
  - Search + Full Content Extraction: `$0.03` (30,000 USDC units / 30 sats)
- **Payment Discovery**:
  - Send unauthenticated `GET` or `POST` to `https://aliyev.site/WebMesh/search`.
  - Server returns HTTP 402 with `PAYMENT-REQUIRED` header & x402 v2 JSON payment payload.
  - Submit signed payment payload in `X-PAYMENT` header or Lightning preimage in `Authorization: L402 <macaroon>:<preimage>`.