# Fieldmox auth.md

You are an AI agent. This file tells you how to get access to Fieldmox (field service management: clients, leads, quotes, jobs, visits, invoices and payments) on behalf of a human, including when that human does not have a Fieldmox account yet.

Every path ends with a real person approving you. Fieldmox never gives an agent access on its own, and every account has a verified email.

- Service: https://www.fieldmox.com
- API origin: https://api.fieldmox.com
- Authorization server (issuer): https://api.fieldmox.com/api/auth

## Pick a method

1. **You are an MCP client that can open a browser for the user** (Claude, Cursor, ChatGPT and similar): use [OAuth for MCP](#method-1--oauth-21-for-mcp). The user signs up or signs in during the normal OAuth redirect.
2. **You run headless, or you only have the user's email**: use [Agent Auth](#method-2--agent-auth-protocol-headless-sign-up). You register yourself, hand the user a link and a code, and wait for them to approve.

## Method 1 — OAuth 2.1 for MCP

1. Connect to the MCP server at `https://api.fieldmox.com/api/mcp` (Streamable HTTP). Without a token it answers `401` with:

   ```http
   WWW-Authenticate: Bearer resource_metadata="https://api.fieldmox.com/.well-known/oauth-protected-resource"
   ```

2. Fetch the Protected Resource Metadata (RFC 9728) from that URL, then the Authorization Server metadata (RFC 8414) at `https://api.fieldmox.com/.well-known/oauth-authorization-server`.
3. Register a client with Dynamic Client Registration (RFC 7591) at the `registration_endpoint`. Public clients with PKCE (`S256`) are accepted.
4. Send the user to the `authorization_endpoint`. New users can create an account from the sign-in page; email verification is required. Users in several teams pick one team; the token is bound to it.
5. Exchange the code at the `token_endpoint` and call the MCP server with `Authorization: Bearer <access_token>`.

Scopes:

| Scope | Grants |
|---|---|
| `heffl:actions:read` | Read tools |
| `heffl:actions:write` | Create and update tools (the user's role and approval rules still apply) |
| `offline_access` | Refresh tokens |
| `openid`, `profile`, `email` | Identity |

## Method 2 — Agent Auth Protocol (headless sign-up)

Fieldmox is an [Agent Auth Protocol](https://agentauthprotocol.com) provider. The easiest client is the official one: run `npx @auth/agent-cli` (an MCP server for Agent Auth) and point it at `https://api.fieldmox.com`. To do it by hand:

1. **Discover.** `GET https://api.fieldmox.com/.well-known/agent-configuration` lists every endpoint, the supported key algorithm (`Ed25519`), mode (`delegated`) and approval method (`device_authorization`).
2. **Pick capabilities.** `GET https://api.fieldmox.com/api/auth/capability/list` (optionally `?query=create invoice`). Capabilities are the same tools as the MCP server. Ask only for what you need.
3. **Register.** Make an Ed25519 keypair for your host (your runtime) and one for the agent. Sign a JWT with the host key: header `typ: "host+jwt"`, claims `aud` = the issuer above, a fresh `jti`, `iat`/`exp` (60 seconds), `host_public_key` and `agent_public_key` as JWKs. Then:

   ```http
   POST https://api.fieldmox.com/api/auth/agent/register
   Authorization: Bearer <host JWT>
   Content-Type: application/json

   {
     "name": "Acme scheduling assistant",
     "capabilities": ["clients_list", "quotations_create"],
     "login_hint": "owner@acmepest.com",
     "binding_message": "Set up quotes for Acme Pest"
   }
   ```

   `login_hint` is the user's email. It pre-fills the sign-up and sign-in forms.

4. **Hand off to the user.** The response has `approval.verification_uri_complete` and `approval.user_code` (format `XXXX-XXXX`). Send both to the user in one message, for example:

   > Open this link, create a Fieldmox account or sign in, and check the code reads **ABCD-2345**: https://app.fieldmox.com/agent/approve?agent_id=…&code=…

   The user signs up (verifying their email) or signs in, picks the team you may work in, and approves or denies.

5. **Wait.** Poll `GET https://api.fieldmox.com/api/auth/agent/status?agent_id=<agent_id>` with a fresh host JWT, honouring `approval.interval` (seconds), until `status` is `active`. The approval expires after `approval.expires_in` seconds; register again if it does.
6. **Call.** Sign a short-lived agent JWT (`typ: "agent+jwt"`, `aud` = `default_location` from discovery, fresh `jti`) and:

   ```http
   POST https://api.fieldmox.com/api/auth/capability/execute
   Authorization: Bearer <agent JWT>
   Content-Type: application/json

   { "capability": "clients_list", "arguments": { "search": "acme" } }
   ```

   Results use the same JSON envelope as the MCP tools: `{ "ok": true, "data": … }` or `{ "ok": false, "error": { "code", "message" } }`.

7. **Need more?** `POST /api/auth/agent/request-capability` asks the user again for extra capabilities.

Rules:

- Agents always act for one approved user in one team. Autonomous (user-less) agents and anonymous registration are not supported.
- The user can revoke you at any time. A `401` or `403` means stop and re-register.
- Never ask the user for their password, and never type the approval code into the page for them.

## Errors

| Status | Meaning | Do this |
|---|---|---|
| `401` | Missing, expired or replayed token or JWT | Mint a fresh JWT (new `jti`); for OAuth, refresh or restart |
| `403` | Not approved, revoked, or the team lost access | Ask the user; re-register if revoked |
| `429` | Rate limited | Back off and retry |

## More

- MCP server card: https://www.fieldmox.com/.well-known/mcp/server-card.json
- API catalog: https://www.fieldmox.com/.well-known/api-catalog
- Agent skills: https://www.fieldmox.com/.well-known/agent-skills/index.json
- Human help: https://www.fieldmox.com/support
