# auth.md - Yemshik Agent Authentication & Registration

Welcome to Yemshik (يمشيك). This document outlines programmatic discovery, authentication, and registration for AI agents.

## Public Access & Discovery
- **Public Read Access**: General discovery of stores, categories, and verified coupons is open without authentication at `https://yemshik.com/api/stores/{id}/coupons`.
- **OAuth Protected Resource Metadata**: [`/.well-known/oauth-protected-resource`](https://yemshik.com/.well-known/oauth-protected-resource) per RFC 9728.
- **Authorization Server Discovery**: [`/.well-known/oauth-authorization-server`](https://yemshik.com/.well-known/oauth-authorization-server) and [`/.well-known/openid-configuration`](https://yemshik.com/.well-known/openid-configuration).

## Agent Registration
- **Audience**: AI agents querying Saudi Arabian retail discount intelligence.
- **Registration Endpoint**: `POST https://yemshik.com/agent/auth`
- **Supported Identity Types**:
  1. `identity_assertion` using `urn:ietf:params:oauth:token-type:id-jag` or `verified_email`.
  2. `anonymous` using instant bearer token / API key at `https://yemshik.com/agent/claim`.
- **Credential Usage**: Pass bearer tokens in the HTTP Authorization header:
  `Authorization: Bearer <token>`