# Agent Authentication Guide (auth.md)

Welcome to the agent authentication guide for **esgabrielweb.com**. This walkthrough specifies how autonomous AI agents, MCP clients, and developer tools authenticate, register, exchange tokens, and interact with the protected and public APIs of this domain.

## Discover

Agents discover authentication capabilities and security policies via standard metadata protocols:
- **Protected Resource Metadata (RFC 9728)**: Located at [/.well-known/oauth-protected-resource](https://esgabrielweb.com/.well-known/oauth-protected-resource). Defines resource identifier https://esgabrielweb.com and designated authorization servers.
- **Authorization Server Metadata (RFC 8414)**: Located at [/.well-known/oauth-authorization-server](https://esgabrielweb.com/.well-known/oauth-authorization-server). Advertises token endpoints, grant types, and the `agent_auth` discovery block.
- **Authentication Challenge (`WWW-Authenticate`)**: Protected API entry points issue a `401 Unauthorized` with the following header:
  ```http
  WWW-Authenticate: Bearer resource_metadata="https://esgabrielweb.com/.well-known/oauth-protected-resource"
  ```
- **Agent Auth Metadata**: The authorization server exposes `agent_auth` containing `identity_endpoint`, `claim_endpoint`, `events_endpoint`, and links back to this document (`skill`).

## Pick a method

Agents choose one of three supported credential pathways based on capability:
1. **`service_auth`**: Server-to-server interaction using pre-provisioned WordPress Application Passwords or OAuth2 Client Credentials (`grant_type=client_credentials`).
2. **`identity_assertion`**: Cryptographically signed identity assertions via ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) minted by trusted agent platforms.
3. **`anonymous`**: Read-only public discovery access (e.g., `/llms.txt`, `/openapi.json`, `/.well-known/api-catalog`, `/ask`) requiring zero authentication.

## Register

Automated registration is supported at the authorization server registration endpoint:
- **Endpoint**: https://esgabrielweb.com/oauth/register
- **Method**: `POST`
- **Client Metadata**: Supports Client ID Metadata Documents (`client_id_metadata_document_supported`). Clients may provide their public metadata URL to dynamically configure client profiles.

## Claim

When using agent identity assertion or onboarding:
- **Identity Endpoint**: https://esgabrielweb.com/agent/identity
- **Claim Endpoint**: https://esgabrielweb.com/agent/claim
Agents verify identity assertions and claim temporary operation grants by submitting signed JWT assertions or challenge verifications.

## Exchange

Exchange claims or client credentials for bearer access tokens:
- **Token Endpoint**: https://esgabrielweb.com/oauth/token
- **Grant Types**:
  - `client_credentials`
  - `authorization_code` (with PKCE code challenge method `S256`)
  - `urn:ietf:params:oauth:grant-type:token-exchange`
- **Example Request**:
  ```http
  POST /oauth/token HTTP/1.1
  Host: esgabrielweb.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=client_credentials&client_id=AGENT_CLIENT_ID&client_secret=SECRET&scope=read:posts+mcp:tools
  ```
- **Example Response**:
  ```json
  {
    "access_token": "egw_tok_demo_access_token",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read:posts mcp:tools"
  }
  ```

## Use the access_token

Transmit the obtained token in the HTTP `Authorization` header:
```http
Authorization: Bearer <access_token>
```
For legacy application passwords, use HTTP Basic Authentication:
```http
Authorization: Basic base64(username:application_password)
```

## Errors

All error responses strictly output RFC 6749 and RFC 7807 JSON error payloads with diagnostic resolution hints:
```json
{
  "error": "invalid_token",
  "error_description": "The access token provided has expired or is invalid.",
  "resolution_hint": "Request a fresh token from https://esgabrielweb.com/oauth/token"
}
```

## Revocation

Tokens may be revoked proactively by client request or security event notification:
- **Revocation Endpoint**: https://esgabrielweb.com/oauth/revoke
- **Security Events**: Dispatched and monitored at https://esgabrielweb.com/agent/events for rapid credential invalidation upon compromise.