# auth.md — RepsFinder agent registration

RepsFinder (https://www.qualityrepsfinder.com) is an independent affiliate catalog of
China shopping agents with curated replica products and real QC photos. This document
explains how AI agents can access and use the site's machine-readable endpoints.

## Audience

Autonomous AI agents, assistants and agentic browsers that want to search the catalog,
look up verified agent offers or fetch shipping estimates on behalf of a user.

## Do I need credentials?

**No.** Every machine endpoint on this site is public and read-only:

- `/.well-known/api-catalog` — API catalog (RFC 9727, `application/linkset+json`)
- `/openapi.json` — OpenAPI description of all public endpoints
- `/mcp` — MCP Streamable HTTP server (JSON-RPC 2.0, tools: `search_products`,
  `list_categories`, `get_agent_offers`, `estimate_shipping`)
- `/health.json` — health endpoint
- `/.well-known/ai-catalog.json` — ARD capability manifest
- `/.well-known/agent-skills/index.json` — agent skills discovery index
- `/catalog.html?q=<query>` and `/category/<category>` — HTML catalog pages

## Optional bearer tokens

Although the API is public, an optional OAuth 2.0 bearer token can be obtained with the
`client_credentials` grant so requests are attributable:

```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=public&scope=public
```

- Token endpoint: `https://www.qualityrepsfinder.com/oauth/token`
- Access tokens are signed ES256 JWTs; public keys at `/.well-known/jwks.json`
- Protected resource metadata: `/.well-known/oauth-protected-resource`
- Authorization server metadata: `/.well-known/oauth-authorization-server`
- Send the token as `Authorization: Bearer <token>` (header method only)
- Tokens expire after 1 hour; request a new one when it does. No refresh flow.

## Standalone registration flow

No account, approval or provisioning step exists. A fully self-contained flow,
discoverable without any prior knowledge of this site:

1. Fetch `https://www.qualityrepsfinder.com/.well-known/oauth-protected-resource`
   (RFC 9728). It returns `resource`, `authorization_servers` and
   `scopes_supported`.
2. Take the issuer from `authorization_servers` and fetch
   `https://www.qualityrepsfinder.com/.well-known/oauth-authorization-server`
   (RFC 8414) to discover `token_endpoint`, `grant_types_supported` and the
   `agent_auth` registration block (`register_uri` points back to this file).
3. Register yourself as an agent: nothing to do — any `client_id` is accepted.
   If you want to be known, email legal@qualityrepsfinder.com with your agent
   name and user agent string.
4. Obtain a token:

   ```
   POST https://www.qualityrepsfinder.com/oauth/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=client_credentials&client_id=<your-client-id>&scope=public
   ```

5. Call any public endpoint with `Authorization: Bearer <token>`:

   ```
   GET https://www.qualityrepsfinder.com/mcp
   Authorization: Bearer <token>
   ```

6. Verify the token's ES256 signature against `/.well-known/jwks.json` if you
   need to validate it client-side. When the token expires (1 hour), repeat
   step 4.

## Registration

No registration, client ID approval or provisioning step is required. Any agent may use
the endpoints within the usage policy below. For higher-volume access or questions,
contact legal@qualityrepsfinder.com.

## Usage policy

- Read-only: do not attempt to write, scrape at abusive rates or bypass rate limits.
- Respect `robots.txt` (including its `Content-Signal` preferences: content must not be
  used for AI training).
- Affiliate links in catalog data are sponsored; disclose them to end users.

## Related discovery documents

- `/auth.md` (this file: `https://www.qualityrepsfinder.com/auth.md`)
- `/.well-known/api-catalog` (RFC 9727)
- `/.well-known/oauth-authorization-server` (RFC 8414)
- `/.well-known/oauth-protected-resource` (RFC 9728)
- `/.well-known/mcp/server-card.json` (MCP SEP-1649)
- `/.well-known/agent-skills/index.json` (Agent Skills Discovery)
- `/.well-known/ai-catalog.json` (ARD)