# auth.md

You are an agent. Turkish Law Blog publishes agent registration discovery so you can find how to authenticate to this resource. Follow discovery first; do not skip to registration.

- Resource server: `https://turkishlawblog.com`
- Authorization server: `https://turkishlawblog.com`
- Skill (this file): `https://turkishlawblog.com/auth.md`
- Contact: baris@barisagun.com

Protected Resource Metadata at `https://turkishlawblog.com/.well-known/oauth-protected-resource` is authoritative if anything in this file conflicts with it.

## 1. Discover

Unauthenticated calls to protected APIs return:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://turkishlawblog.com/.well-known/oauth-protected-resource"
```

### 1a. Fetch Protected Resource Metadata

```http
GET /.well-known/oauth-protected-resource
```

Read `resource`, `resource_name`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`. Tokens are presented as `Authorization: Bearer <access_token>` (`bearer_methods_supported: ["header"]`).

### 1b. Fetch Authorization Server metadata

```http
GET /.well-known/oauth-authorization-server
```

Read `issuer`, `authorization_endpoint`, `token_endpoint`, `jwks_uri`, `grant_types_supported`, and the `agent_auth` block:

- `skill` — this document
- `register_uri` / `identity_endpoint` — `https://turkishlawblog.com/agent/auth`
- `claim_uri` / `claim_endpoint` — `https://turkishlawblog.com/agent/auth/claim`
- `revocation_uri` — `https://turkishlawblog.com/agent/auth/revoke`
- `events_endpoint` — `https://turkishlawblog.com/agent/auth/events`
- `identity_types_supported` — `anonymous`, `identity_assertion`
- `identity_assertion.assertion_types_supported` — `verified_email`
- `anonymous.credential_types_supported` / `identity_assertion.credential_types_supported` — `access_token`

## 2. Pick a method

1. You have a verified user email to bind — `identity_assertion` with `verified_email`. A human must complete claim at Turkish Law Blog.
2. You have no user identity yet — `anonymous`. A human can later claim the registration at Turkish Law Blog.

ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) is not listed in `assertion_types_supported`. Do not send ID-JAGs.

## 3. Register

Registration does not silently create Turkish Law Blog accounts. POST the method you chose; the response tells you how the human completes claim.

### identity_assertion + verified_email

```http
POST /agent/auth
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "login_hint": "user@example.com"
}
```

### anonymous

```http
POST /agent/auth
Content-Type: application/json

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

Both methods return JSON describing `claim_uri`, the human register URL (`https://turkishlawblog.com/register`), and the human login URL (`https://turkishlawblog.com/login`).

## 4. Claim

The user signs in or creates an account on Turkish Law Blog, then the agent may poll or re-POST the claim endpoint.

- Human register: `https://turkishlawblog.com/register`
- Human login: `https://turkishlawblog.com/login`
- Agent claim: `https://turkishlawblog.com/agent/auth/claim`

```http
POST /agent/auth/claim
Content-Type: application/json

{
  "login_hint": "user@example.com"
}
```

## 5. Use credentials

Supported scopes: openid, email, profile, phone, offline_access.

After the user has an Turkish Law Blog session, call protected APIs with the access token in the Authorization header:

```http
Authorization: Bearer <access_token>
```

## 6. Revocation

To revoke agent correspondence or request deletion of a registration:

```http
POST /agent/auth/revoke
Content-Type: application/json
```

Or email baris@barisagun.com with subject `agent revocation`.

Provider-originated revocation events are advertised at `events_endpoint` (`https://turkishlawblog.com/agent/auth/events`). Turkish Law Blog does not ingest Security Event Tokens yet; treat an `invalid_grant` on token use as a signal to restart registration.

## Related discovery

- Protected resource metadata: `https://turkishlawblog.com/.well-known/oauth-protected-resource`
- Authorization server metadata: `https://turkishlawblog.com/.well-known/oauth-authorization-server`
- API catalog: `https://turkishlawblog.com/.well-known/api-catalog`
- ARD catalog: `https://turkishlawblog.com/.well-known/ai-catalog.json`
- Site index: `https://turkishlawblog.com/llms.txt`