# auth.md — כתבות תוכן agent registration

This service supports **agentic registration** for a deliberately limited, read-only OAuth surface. The registration flow never creates a WordPress administrator, never exposes drafts, and never grants write access.

Protected resource identifier: `https://katavot.co.il`

Read-only API endpoint: `https://katavot.co.il/agentready-api`

Authorization server: `https://katavot.co.il`

## 1. Discover

1. Fetch Protected Resource Metadata: `https://katavot.co.il/.well-known/oauth-protected-resource`. Its `resource` value is exactly `https://katavot.co.il` and it publishes `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`.
2. Fetch OAuth Authorization Server Metadata: `https://katavot.co.il/.well-known/oauth-authorization-server`. Read `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`, and the `agent_auth` block.
3. The read-only API endpoint `https://katavot.co.il/agentready-api` requires a Bearer token and returns `401` when one is missing or invalid.

## 2. Pick a registration method

Supported agent registration type: `anonymous`. It is intentionally unclaimed and read-only. `identity_assertion` and `service_auth` user-binding flows are not enabled.

Available scope:

- `content.read` — read a small index of content that is already public in WordPress.

## 3. Register the agent

POST `https://katavot.co.il/agent/identity` with JSON:

```json
{
  "type": "anonymous"
}
```

A successful response contains `registration_id`, `registration_type`, a short-lived service-signed `identity_assertion`, `assertion_expires`, and the read-only scopes. No access token is issued at registration time.

## 4. Exchange the assertion

POST `https://katavot.co.il/oauth2/token` as `application/x-www-form-urlencoded` using the RFC 7523 JWT bearer grant:

```http
POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<identity_assertion>&resource=https%3A%2F%2Fkatavot.co.il
```

The response is a standard OAuth token envelope containing `access_token`, `token_type=Bearer`, `expires_in`, and `scope`. No refresh token is issued.

## 5. Use the access token

Send `Authorization: Bearer <access_token>` to the protected read-only endpoint `https://katavot.co.il/agentready-api`. The endpoint only returns content WordPress already marks as published and public.

## 6. Errors

- `/agent/identity`: `invalid_request`, `anonymous_not_enabled`/`*_not_enabled`, `temporarily_unavailable`.
- `/oauth2/token`: `invalid_grant`, `unsupported_grant_type`, `invalid_target`.
- Protected API: `401 invalid_token` when the Bearer token is missing or invalid.

## 7. Revocation

POST the bearer token as `token=<access_token>` to `https://katavot.co.il/oauth2/revoke`. Revocation is idempotent. Revoking an access token does not revoke the short-lived identity assertion; that assertion may be re-exchanged until it expires. After the assertion expires, register again.

## Security boundaries

This AgentReady OAuth profile is intentionally limited to anonymous `content.read` access. It does not authenticate a human user, does not create accounts, does not expose WordPress administration, and does not authorize write operations.