# UES Consultants auth.md

Agent authentication guide for Ultimate Environmental Solutions, Inc. (UES Consultants), https://uesconsultants.com.
Machine-readable metadata: `https://uesconsultants.com/.well-known/oauth-authorization-server` and
`https://uesconsultants.com/.well-known/oauth-protected-resource`.

## Who this is for

AI agents and assistants acting for Florida homeowners, buyers, landlords and
property managers who want information from UES or want UES to call a customer
back about a mold or indoor air quality assessment.

## What needs no credentials

Everything that only reads: the website, `/llms.txt`, `GET /api/agent/*`
(info, services, service-area, triage, search), the MCP server at `/mcp`
(all tools except `request_assessment`) and the A2A agent at `/a2a` (all skills
except `request-assessment`).

## What needs a token

Placing an assessment request, which creates a lead the UES office will call:

- `POST https://uesconsultants.com/api/agent/leads`
- MCP tool `request_assessment` on `https://uesconsultants.com/mcp`
- A2A skill `request-assessment` on `https://uesconsultants.com/a2a`

Send `Authorization: Bearer <access_token>` with scope `leads:write`.
Unauthenticated calls return `401` with
`WWW-Authenticate: Bearer resource_metadata="https://uesconsultants.com/.well-known/oauth-protected-resource"`.

## Register (anonymous, RFC 7591)

`POST https://uesconsultants.com/oauth/register` with JSON. No account or approval is needed; the
response is the only copy of your credentials (nothing is stored server-side,
the client id is a signed token).

Customer-confirmed agent (public client, PKCE):

```json
{"client_name": "Acme Home Assistant", "client_uri": "https://acme.example",
 "redirect_uris": ["https://acme.example/oauth/callback"],
 "token_endpoint_auth_method": "none", "grant_types": ["authorization_code"]}
```

Server-to-server agent (confidential client):

```json
{"client_name": "Acme Concierge", "token_endpoint_auth_method": "client_secret_basic",
 "grant_types": ["client_credentials"], "contacts": ["ops@acme.example"]}
```

## Get a token

### authorization_code + PKCE (preferred)

1. Send the customer to `https://uesconsultants.com/oauth/authorize?response_type=code&client_id=<id>&redirect_uri=<uri>&scope=leads:write&state=<state>&code_challenge=<S256>&code_challenge_method=S256`.
2. On uesconsultants.com the customer confirms the name and phone UES may call
   (that is the "claim" step: a human attaches real contact details to your
   anonymous registration).
3. You receive `?code=...&state=...`. Exchange it: `POST https://uesconsultants.com/oauth/token`
   (`application/x-www-form-urlencoded`) with `grant_type=authorization_code`,
   `code`, `redirect_uri`, `client_id`, `code_verifier`.
4. The access token (1 hour) carries the confirmed contact; leads you place with
   it are marked **customer confirmed**, and the contact fields in your request
   body are ignored in favour of what the customer typed.

### client_credentials

`POST https://uesconsultants.com/oauth/token` with `grant_type=client_credentials&scope=leads:write`
and HTTP Basic (`client_id:client_secret`). Leads placed with this token are
marked **agent supplied, not yet verified**; the office verifies by phone.

## Scopes

- `read`: public information (also available without a token)
- `leads:write`: place assessment requests

## Tokens

RS256 JWTs, issuer `https://uesconsultants.com`, audience `https://uesconsultants.com`, verified with
`https://uesconsultants.com/.well-known/jwks.json`. Access tokens expire after 3600 seconds; request
a new one rather than refreshing (no refresh tokens).

## Revocation

Credentials are stateless and expire on their own (client secrets after 2 years,
access tokens after 1 hour). To have a client blocked earlier, email
inquiries.ues@gmail.com with the `client_name` and the time of registration, or call
(407) 438-4684.

## Rules of engagement

- Only submit a request with the customer's explicit consent; never invent
  contact details.
- Do not retry a successful (201) request.
- Unsolicited vendor or marketing content is filtered and never reaches the office.
- Rate limits: 20 registrations per hour per IP, 60 token requests per 10
  minutes, 10 lead requests per hour per client.

## Related

- Developer guide: https://uesconsultants.com/developers
- OpenAPI: https://uesconsultants.com/.well-known/openapi.json
- API catalog: https://uesconsultants.com/.well-known/api-catalog
- Agent skills: https://uesconsultants.com/.well-known/agent-skills/index.json