# Zkawa auth.md

Zkawa publishes this `auth.md` file so AI agents can discover the planned agent registration surface for Zkawa's public real estate APIs.

Current status: agent registration endpoints are reserved for future token-based agent API access. Zkawa's public listing discovery APIs are currently read-only and unauthenticated, and the portal continues to use cookie-based user sessions.

## Step 1 - Discover metadata

Fetch the Protected Resource Metadata:

```http
GET https://zkawa.com/.well-known/oauth-protected-resource
Accept: application/json
```

Then fetch the Authorization Server metadata from the first `authorization_servers` entry:

```http
GET https://zkawa.com/.well-known/oauth-authorization-server
Accept: application/json
```

The authorization server metadata contains the `agent_auth` block with the registration endpoints and reserved flow metadata.

## Service

- Service name: Zkawa
- Resource: `https://zkawa.com`
- Protected Resource Metadata: `https://zkawa.com/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://zkawa.com/.well-known/oauth-authorization-server`
- JWKS: `https://zkawa.com/.well-known/jwks.json`
- Agent registration guide: `https://zkawa.com/auth.md`

## Supported scopes

- `properties:read` - read public property listing data.
- `markets:read` - read public market and city summary data.

## Agent registration endpoints

- Register: `POST https://zkawa.com/agent/auth`
- Start claim: `POST https://zkawa.com/agent/auth/claim`
- Complete claim: `POST https://zkawa.com/agent/auth/claim/complete`
- Revoke: `POST https://zkawa.com/agent/auth/revoke`

These endpoints are reserved today and return `501 temporarily_unavailable` until agent credential issuance is enabled.

## Reserved flows

The discovery metadata reserves the following auth.md flow names so agents can understand the intended shape:

- `anonymous` with `api_key` credentials.
- `identity_assertion` with `urn:ietf:params:oauth:token-type:id-jag` assertions.
- `identity_assertion` with `verified_email` assertions.

Do not assume credentials can be issued until the registration endpoints return success responses. For now, use public unauthenticated discovery APIs and WebMCP tools.

## Public read-only APIs

Agents can currently use these unauthenticated public endpoints:

- `GET https://zkawa.com/public/api/properties`
- `GET https://zkawa.com/public/api/properties/{property_id_or_slug}`
- `GET https://zkawa.com/public/api/properties/top-markets`
- `GET https://zkawa.com/public/api/properties/top-cities`
- `GET https://zkawa.com/public/api/properties/top-zips`

## Credential use

When agent registration is enabled, Zkawa expects to support scoped `api_key` and `access_token` credential types as advertised in the `agent_auth` metadata. Credentials will be sent using the standard HTTP bearer header:

```http
Authorization: Bearer <credential>
```

Until then, protected or reserved endpoints can return:

```http
WWW-Authenticate: Bearer resource_metadata="https://zkawa.com/.well-known/oauth-protected-resource"
```

## Revocation

When agent registration is enabled, agents and agent providers should use the advertised revocation endpoint:

```http
POST https://zkawa.com/agent/auth/revoke
```

The `agent_auth.events_supported` metadata advertises the identity assertion revocation event:

```txt
https://schemas.workos.com/events/agent/auth/identity/assertion/revoked
```

## Errors

- `temporarily_unavailable` - agent credential issuance is reserved but not active.
- `unsupported_registration_type` - requested registration type is not supported.
- `invalid_scope` - requested scopes are not advertised in metadata.
- `invalid_request` - request body is missing required fields.

## Terms and privacy

- Terms: `https://zkawa.com/terms`
- Privacy: `https://zkawa.com/privacy`
- Agent documentation: `https://zkawa.com/llms.txt`