# auth.md

Agent authentication and registration for **Pomona Organic Juices** (https://www.pomonaorganic.com).

## Audience

AI agents, shopping assistants and automated clients that want to read Pomona product data or act on behalf of a signed-in customer.

## Most agents need no credentials

Everything below is public, CORS-open and requires **no token and no registration**:

- Live product catalog: `https://snbtuvyzyiikedlmgmxr.supabase.co/functions/v1/agent-catalog`
- API description: https://www.pomonaorganic.com/api/openapi.json
- API documentation: https://www.pomonaorganic.com/api/
- Product records: https://www.pomonaorganic.com/kb/products.json
- Knowledge base: https://www.pomonaorganic.com/kb/pomona-knowledge-base.md
- Merchant feed: https://www.pomonaorganic.com/feed.xml
- Sitemap: https://www.pomonaorganic.com/sitemap.xml
- Usage guide: https://www.pomonaorganic.com/llms.txt

Register only if you need account-scoped access on behalf of a specific customer.

## Discovery

| Document | URL |
| --- | --- |
| Protected resource metadata (RFC 9728) | https://www.pomonaorganic.com/.well-known/oauth-protected-resource |
| Authorization server metadata (RFC 8414) | https://www.pomonaorganic.com/.well-known/oauth-authorization-server |
| OpenID Connect discovery | https://www.pomonaorganic.com/.well-known/openid-configuration |
| API catalog (RFC 9727) | https://www.pomonaorganic.com/.well-known/api-catalog |
| Agent descriptor | https://www.pomonaorganic.com/.well-known/agent.json |

Token issuer: `https://snbtuvyzyiikedlmgmxr.supabase.co/auth/v1` — all authorize, token, registration, revocation and JWKS endpoints are operated there, and it publishes its own RFC 8414 document. The documents above are published on `https://www.pomonaorganic.com` so agents that start from this site can discover them in one hop.

Revocation: `POST https://snbtuvyzyiikedlmgmxr.supabase.co/auth/v1/oauth/revoke` (RFC 7009) to revoke an access or refresh token.

## Registration

Clients register themselves — no manual approval, no email, no contract.

```
POST https://snbtuvyzyiikedlmgmxr.supabase.co/auth/v1/oauth/clients/register
Content-Type: application/json

{
  "client_name": "Your Agent",
  "redirect_uris": ["https://your-agent.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

The response contains your `client_id` (and a `client_secret` if you requested a confidential client). Treat both as secrets.

## Obtaining a token

OAuth 2.0 authorization code flow with PKCE (`S256`).

1. Send the customer to `https://snbtuvyzyiikedlmgmxr.supabase.co/auth/v1/oauth/authorize` with your `client_id`, `redirect_uri`, `response_type=code`, `scope`, `state` and `code_challenge`.
2. The customer signs in and approves on a Pomona-hosted consent screen.
3. Exchange the returned code at `https://snbtuvyzyiikedlmgmxr.supabase.co/auth/v1/oauth/token` with your `code_verifier`.
4. Refresh with `grant_type=refresh_token`.

Supported scopes: `openid`, `profile`, `email`, `offline_access`.
Public keys for token verification: `https://snbtuvyzyiikedlmgmxr.supabase.co/auth/v1/.well-known/jwks.json`

## Using credentials

Send the access token as a bearer token in the request header:

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

Tokens are short-lived; refresh rather than re-running the full flow. Never place a token in a URL. A customer can revoke access at any time by signing out of their Pomona account, which invalidates the refresh token.

## What agents may do

- Read, quote and cite any public product, nutrition, policy or article content. Please attribute Pomona Organic Juices and link to the product URL.
- Recommend products and link customers to the product page to buy.

## What agents may not do

- There are **no** cart, order, payment or fulfilment endpoints. Checkout is completed by a person on pomonaorganic.com. Do not attempt to automate purchases.
- Do not scrape faster than roughly 60 requests per minute.
- Do not use the content to train models; see https://www.pomonaorganic.com/robots.txt for our content signals.

## Contact

info@pomonaorganic.com — https://www.pomonaorganic.com/contact