# Township Canada auth.md

How AI agents and the software they run get access to the Township Canada API.

## Audience

Agents and applications calling the Township Canada API on behalf of a person or organization that holds a Township Canada API subscription. The API converts Canadian legal land descriptions to GPS coordinates and back, and returns agriculture and energy parcel reports.

## AI apps (MCP)

AI apps such as ChatGPT and Claude connect to the Township Canada MCP server at `https://townshipcanada.com/mcp` with OAuth 2.1, acting for a person with an active Pro or Business plan. No API key is involved.

Add the published [Township Canada community connector](https://claude.ai/directory/connectors/township-canada) from the Claude Connectors Directory. ChatGPT and other compatible hosts can add a custom MCP connection using the server URL above. The Township Canada plugin uses this same connection and adds conversion and parcel-report skills.

- Discovery: `https://townshipcanada.com/.well-known/oauth-protected-resource/mcp` (RFC 9728) and `https://townshipcanada.com/.well-known/oauth-authorization-server` (RFC 8414). An unauthenticated request to `/mcp` returns `401` with a `WWW-Authenticate` challenge naming both.
- Clients: public clients only, identified by a Client ID Metadata Document or dynamic client registration at `/oauth/register`. PKCE with S256 is required. Tokens are bound to the `/mcp` resource.
- Scopes: `land:read` (convert descriptions and coordinates, batch convert, read parcel reports within the account's plan) and `account:read` (the account's plan, add-ons and remaining allowances).
- The person signs in with their normal Township Canada login and approves the connection. They can disconnect it from their account page at any time.

Setup for people: https://townshipcanada.com/ai
Step-by-step guide: https://townshipcanada.com/guides/chatgpt-claude

## Registration (API keys)

There is no self-service registration or OAuth flow for the API. Access is provisioned by a person:

1. Sign in at https://townshipcanada.com/login (email one-time code, magic link, Google or Microsoft; there are no passwords).
2. Open the developer portal at https://townshipcanada.com/app/api.
3. Subscribe to each API you need. Each API is its own subscription with its own key: Search, Autocomplete, Batch, Ag Report, Energy Report, and the Maps, Ag Maps and Energy Maps tile APIs.
4. Copy the issued key from the developer portal and give it to the agent as a secret.

Keys can be rotated or deleted from the developer portal at any time.

## Using credentials

- Search, Autocomplete, Batch, Ag Report and Energy Report APIs (`https://developer.townshipcanada.com`): send the key in the `X-API-Key` request header.
- Maps, Ag Maps and Energy Maps tile APIs (`https://maps.townshipcanada.com`): send the key as the `api_key` query parameter.

```bash
curl "https://developer.townshipcanada.com/search/legal-location?location=NW-25-24-1-W5" \
  -H "X-API-Key: $TOWNSHIP_CANADA_API_KEY"
```

A missing or invalid key returns `401`. A request over the plan's monthly quota or rate returns `429`; back off and retry later. Treat keys as secrets: never log them or expose them in client-side code you don't control.

## References

- API documentation: https://townshipcanada.com/api
- OpenAPI specification: https://townshipcanada.com/openapi.yaml
- API catalog: https://townshipcanada.com/.well-known/api-catalog
- Agent skill: https://townshipcanada.com/.well-known/agent-skills/township-canada-api/SKILL.md
- MCP server card: https://townshipcanada.com/.well-known/mcp/server-card.json
