# auth.md

Tellico Tractor Works — Agent Authentication & Registration Discovery

This document describes how autonomous agents (AI assistants, crawlers, and
other software agents) authenticate, register, and obtain credentials to access
the Tellico Tractor Works website API surface.

## Audience

This `auth.md` is intended for software agents that consume the public HTTP
resources of `https://www.tellicotractorworks.com`, including:

- The RFC 9727 API catalog at `/.well-known/api-catalog`
- The OpenAPI 3.1 service description at `/api/openapi.json`
- The human-readable API documentation at `/api/docs.html`
- The health endpoint at `/api/health.json`
- The public website pages (`/`, `/services`, `/contact`, `/reviews`, and the
  service/location pages documented in the OpenAPI specification)

## Current access model

The resources listed above are **public** and do not require authentication for
read access. Ordinary HTTP `GET` requests are served without credentials.

Agents that need elevated or future protected access (for example, write
operations or rate-limit-exempt programmatic access) must register and obtain
credentials as described below.

## OAuth Protected Resource Metadata

The resource server publishes OAuth Protected Resource Metadata (RFC 9728) at:

```
/.well-known/oauth-protected-resource
```

That document advertises the `resource` identifier, the `authorization_servers`
that may issue access tokens for this resource, the `scopes_supported`, and the
`bearer_methods_supported` (which includes `header`).

## OAuth Authorization Server Metadata

The authorization server advertised in the Protected Resource Metadata publishes
its metadata (RFC 8414) at:

```
/.well-known/oauth-authorization-server
```

The `issuer` value in that document is
`https://www.tellicotractorworks.com` and matches the issuer advertised in the
Protected Resource Metadata. The Authorization Server metadata also contains an
`agent_auth` block that points back to this `auth.md` as the `skill` document and
advertises the agent registration endpoint (`register_uri`).

## Agent registration

Agents register for credentials through the registration endpoint advertised in
the `agent_auth.register_uri` field of the Authorization Server metadata.

### Supported registration method

**Email provisioning (mailto)**

- **URI:** `mailto:tellicotractorworks@icloud.com`
- **Register URI:** `https://www.tellicotractorworks.com/contact`
- **Description:** Send a registration request to
  `tellicotractorworks@icloud.com` (or use the contact form at
  `/contact`) identifying the agent, its operator, the intended scope of access,
  and a public key or client identifier to provision. Tellico Tractor Works
  provisions credentials out-of-band and returns a client identifier and
  credential (bearer token or client secret) along with the scopes granted.

### Credential use

Issued credentials are **bearer tokens** presented in the HTTP `Authorization`
header using the `Bearer` scheme:

```
Authorization: Bearer <token>
```

This corresponds to `bearer_methods_supported: ["header"]` in the Protected
Resource Metadata. Tokens are scoped to the `scopes_supported` advertised in both
metadata documents. Treat credentials as secrets; do not embed them in
client-side code or commit them to repositories.

## Discovery summary

| Document | URL |
| --- | --- |
| This auth.md | `/auth.md` |
| OAuth Protected Resource Metadata | `/.well-known/oauth-protected-resource` |
| OAuth Authorization Server Metadata | `/.well-known/oauth-authorization-server` |
| API catalog (RFC 9727) | `/.well-known/api-catalog` |
| OpenAPI 3.1 spec | `/api/openapi.json` |
| API docs | `/api/docs.html` |
| Health | `/api/health.json` |

## Contact

- **Phone:** 423-509-5565
- **Email:** tellicotractorworks@icloud.com
- **Contact page:** https://www.tellicotractorworks.com/contact