---
title: "FieldRobin OAuth and MCP authentication guide"
description: "OAuth client registration and granular permissioned MCP access for FieldRobin agent clients."
canonical_url: https://fieldrobin.com/auth.md
markdown_url: https://fieldrobin.com/auth.md
content_type: authentication_guide
product: "FieldRobin"
company: "Doorkeeper Labs LLC"
updated_at: 2026-09-10
language: en
---
# auth.md

FieldRobin exposes an OAuth 2.0 protected MCP service with 45 read tools and two scope-authorized write tools for authorized agent clients. The authenticated catalog publishes a revision and hash so clients can refresh cached tools after a contract change.

This document describes the discovery-only OAuth client registration flow currently supported by FieldRobin. It creates an OAuth client for an MCP application; it does not create a FieldRobin user, business, or customer account.

## Step 1 — Discover

Fetch these public documents before registering or authorizing a client:

- Protected Resource Metadata: https://fieldrobin.com/.well-known/oauth-protected-resource
- Authorization Server Metadata: https://fieldrobin.com/.well-known/oauth-authorization-server
- Authorization Server JWKS: https://fieldrobin.com/api/v1/oauth/jwks
- MCP resource: https://fieldrobin.com/api/v1/mcp

The protected resource is `https://fieldrobin.com/api/v1/mcp`, the authorization server issuer is `https://fieldrobin.com`, and the supported scopes are `mcp:read`, `mcp:customers:write`, `mcp:jobs:write`, broad compatibility scope `mcp:write`, and legacy read-only scope `mcp:use`. New dynamic registrations request `mcp:read mcp:customers:write mcp:jobs:write` by default; the consent page lets the user grant read-only access, customer writes, job writes, or both.

## Developer resources

- OpenAPI: https://fieldrobin.com/openapi.json
- REST versioning and deprecation: https://fieldrobin.com/api-versioning.md
- Developer index: https://fieldrobin.com/developers
- Webhook integration guide: https://fieldrobin.com/webhooks.md

## Supported flows

- OAuth client registration for a protected MCP client, followed by Authorization Code with PKCE (`S256`).

## Scopes

- `mcp:read` — access to the authenticated MCP read tools.
- `mcp:customers:write` — direct access to the `create-customer` tool in addition to `mcp:read`.
- `mcp:jobs:write` — direct access to the `create-job` tool in addition to `mcp:read`.
- `mcp:write` — broad compatibility scope for all currently exposed MCP write tools in addition to `mcp:read`. Prefer the granular scopes for least privilege.
- `mcp:use` — legacy read-only compatibility scope for existing clients.

Read-only tokens can discover write tools with per-tool required-scope metadata. If a client calls one without its required write scope, FieldRobin returns HTTP 403 with `MCP_WRITE_SCOPE_REQUIRED`, the missing `required_scopes`, and protected-resource metadata. The MCP client must run its own Authorization Code + PKCE step-up flow, obtain a new grant with explicit user consent, and retry the call once. FieldRobin never broadens an existing token silently.

## Step 2 — Supported registration method

FieldRobin currently supports `oauth_client_registration` for MCP clients. The client must use Authorization Code flow with PKCE (`S256`) and a registered redirect URI.

This deployment does not currently publish or accept the Auth.md identity types `identity_assertion`, `verified_email`, `anonymous`, or `service_auth`. Do not send those registration shapes to FieldRobin.

## Step 3 — Register an OAuth client

Only register when the user intends to connect the MCP client. Registration creates a persistent public OAuth client record.

- Method: `POST`
- URI: https://fieldrobin.com/api/oauth/register
- Content-Type: `application/json`
- Required field: `redirect_uris` — a non-empty array of permitted redirect URIs
- Optional fields: `client_name`, `name`, or `scope` (new registrations default to `mcp:read mcp:customers:write mcp:jobs:write`; use an explicit scope only when the client intentionally needs a narrower grant)

Every URI in `redirect_uris` must be accepted. FieldRobin supports configured HTTPS client domains, vetted hosted callbacks on `claude.ai`, `chatgpt.com`, `www.cursor.com`, `vscode.dev`, and `insiders.vscode.dev`, HTTP loopback callbacks such as `http://127.0.0.1:<port>/callback` when enabled, and configured private-use schemes such as `cursor://`.

Example request:

```http
POST https://fieldrobin.com/api/oauth/register
Content-Type: application/json

{
  "client_name": "Example MCP client",
  "redirect_uris": ["https://client.example/callback"]
}
```

The redirect URI must satisfy the authorization server's configured allowlist. A successful response returns `client_id`, `redirect_uris`, `grant_types`, `response_types`, a granted `scope` (normally `mcp:read mcp:customers:write mcp:jobs:write`), and `token_endpoint_auth_method: none`.

## Step 4 — Authorize and obtain a token

1. Start Authorization Code flow at https://fieldrobin.com/api/oauth/authorize using the registered `client_id`, exact `redirect_uri`, the registered `scope` (normally `mcp:read mcp:customers:write mcp:jobs:write`; use `mcp:read` only for an intentionally read-only client), `response_type=code`, a random `state`, and a PKCE `code_challenge` with `code_challenge_method=S256`. This opens a browser login and consent flow. The user can deselect optional write scopes before approving; after sign-in (and email verification when required), the browser returns to the authorization request.
2. After the user approves access, exchange the returned authorization code at https://fieldrobin.com/api/oauth/token with the matching `code_verifier`.
3. Call https://fieldrobin.com/api/v1/mcp with `Authorization: Bearer <access_token>`.

MCP reads and scope-authorized writes are scoped to the business bound to the authenticated MCP connection. `create-customer` and `create-job` persist directly and return an authoritative verified result only when the matching write scope is granted. Do not request or expose customer data outside the granted MCP session.

## Errors and safety

- Do not retry registration blindly; a successful registration creates a client record.
- If the redirect URI is rejected, correct it instead of weakening validation.
- If the access token is rejected, rediscover OAuth metadata and restart the authorization flow; never ask the user to paste a private key or token into an untrusted channel.
- After a code-only server fix, keep the existing token. Start a new MCP session or call `tools/list` to refresh the catalog; reauthorize only when the error names a missing scope or the grant is revoked.
- FieldRobin does not expose authenticated application routes or tenant data through public discovery documents.

## Future Auth.md flows

User-claimed and agent-verified registration flows are not enabled by this document. They will be advertised only after FieldRobin implements their identity, consent, token, revocation, and audit behavior.