# Critter-Ridder Auth.md

Critter-Ridder exposes public, read-only agent capabilities. This OAuth 2.0 service uses the client credentials grant for machine identities; it does not create a customer account or authorize changes to a property, appointment, price, or service scope.

## Discover

- Authorization server metadata: https://www.critterridder.net/.well-known/oauth-authorization-server
- Site protected-resource metadata: https://www.critterridder.net/.well-known/oauth-protected-resource
- A2A protected-resource metadata: https://www.critterridder.net/.well-known/oauth-protected-resource/api/a2a
- Public signing keys: https://www.critterridder.net/oauth/jwks.json
- Site resource identifier: https://www.critterridder.net
- A2A resource identifier: https://www.critterridder.net/api/a2a
- A2A Agent Card: https://www.critterridder.net/.well-known/agent-card.json

## Register an anonymous agent identity

Send JSON to either https://www.critterridder.net/oauth/register or https://www.critterridder.net/agent/identity:

```http
POST /oauth/register
Content-Type: application/json

{"type":"anonymous","client_name":"Example read-only agent"}
```

The response contains a client ID, one-year client secret, and a one-use claim token valid for 24 hours. Protect the client secret and claim token. Anonymous registrations receive only these scopes: business.read, services.read, areas.read, a2a.invoke.

## Claim the registration

To begin a claim, send the claim token and intended user's email address to https://www.critterridder.net/agent/identity/claim. The response contains a separate claim-attempt token, a one-use user code, and a verification URL. Show the URL and code to that user. They open the URL in a top-level browser window, sign in with ChatGPT using the same email, and enter the code. The attempt expires after 10 minutes and locks after five incorrect codes.

    POST /agent/identity/claim
    Content-Type: application/json

    {"claim_token":"CLAIM_TOKEN","email":"user@example.com"}

The anonymous credential can use its read-only scopes before claim. Claiming records ownership and does not expand those scopes. The agent-held claim token is never placed in the browser URL.

## Obtain a short-lived access token

Use HTTP Basic authentication or send `client_id` and `client_secret` in the form body:

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

grant_type=client_credentials&scope=a2a.invoke&resource=https://www.critterridder.net/api/a2a
```

Successful responses contain an Ed25519-signed bearer token valid for 15 minutes. Present it in the `Authorization: Bearer` header when calling https://www.critterridder.net/api/a2a.

## Revoke credentials

Send an RFC 7009 form request to https://www.critterridder.net/oauth/revoke using HTTP Basic authentication or client credentials in the form body. Pass the access token or client secret in the token field and use access_token or client_secret as the token_type_hint. Revoking an access token blocks it immediately. Revoking the client secret disables the registration and every access token issued to it. Repeating a valid revocation request is safe.

    POST /oauth/revoke
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic BASE64(client_id:client_secret)

    token=ACCESS_TOKEN&token_type_hint=access_token

## Limits

- Registered agents can read public business, service, and published coverage information only.
- They cannot submit the inspection form, schedule service, change records, quote work, or access private customer information.
- The `outbound.verify` scope is reserved for Critter-Ridder's first-party outbound bot and is never granted by anonymous registration.
- Registration, claim, token, and revocation endpoints are rate-limited. Request bodies are size-limited and claim codes lock after five incorrect attempts.
- Claim state and revocations are durable. Expired claim, revocation, and rate-limit records are removed automatically.