# auth.md

You are an agent that helps a home service business owner use ReviewWheel. This file tells you how the owner signs up, how you connect to ReviewWheel by MCP or with an API key, and how to call the ReviewWheel API.

This file is https://reviewwheel.com/auth.md. For what ReviewWheel does, read https://reviewwheel.com/llms.txt. The API reference is https://reviewwheel.com/api, and its OpenAPI 3.1 description is https://reviewwheel.com/openapi.json. The setup steps as an Agent Skill are at https://reviewwheel.com/skill.md.

Three hosts are relevant:

- **Marketing site:** `https://reviewwheel.com`. Plans, terms and privacy.
- **App:** `https://app.reviewwheel.com`. The owner signs up, signs in and manages the account here.
- **API:** `https://api.reviewwheel.com`. The resource server for `/api/v1` and for the MCP server at `/mcp`.

## Current state

You can connect in two ways:

- **MCP:** an AI app with MCP connectors, for example Claude or ChatGPT, connects to Axle, the ReviewWheel MCP server. The person signs in in the browser. See "Connect by MCP".
- **API key:** a headless agent sends a ReviewWheel API key. The owner signs up in the browser and creates the key. See Step 1 to Step 3.

You cannot create an account, a credential or a payment for the owner. Do not call `/agent/identity` or any other agent registration endpoint on a ReviewWheel host. They do not exist. When ReviewWheel adds agent registration, this file changes first.

## Connect by MCP

- **URL:** `https://api.reviewwheel.com/mcp`
- **Transport:** Streamable HTTP. Send JSON-RPC by `POST`. Answers are JSON. There is no event stream.
- **Sign-in:** OAuth through `https://clerk.reviewwheel.com`. The metadata is at `https://api.reviewwheel.com/.well-known/oauth-protected-resource/mcp`. Register your client with a Client ID Metadata Document. Dynamic client registration is off.

The person connects in three steps:

1. Add `https://api.reviewwheel.com/mcp` as a connector in the AI app.
2. Sign in with the ReviewWheel login. A person with no account signs up and connects Google. No plan and no card are needed.
3. Pick the company and approve.

The connection acts as the person who approved it. Their role in ReviewWheel sets the tools they can use, and the app reads the role again on each call. A user can use `get_account`, `list_locations`, `get_reputation_stats`, `list_reviews` and `get_google_performance`, for the locations the app lets them see. An owner or admin can use every tool. `tools/list` shows only the tools the person can use. A call to another tool answers `insufficient-scope`.

| Tool | Route | Needs |
| --- | --- | --- |
| `get_account` | `GET /api/v1/ping` | Nothing |
| `list_locations` | `GET /api/v1/locations` | Nothing |
| `get_plan` | `GET /api/v1/plan` | Owner or admin |
| `get_profile_audit` | `GET /api/v1/profile-audit` | Owner or admin |
| `get_rank_score` | `GET /api/v1/rank/score` | Owner or admin. Rank on the location. |
| `get_reputation_stats` | `GET /api/v1/reputation/stats` | Reputation on the location |
| `list_reviews` | `GET /api/v1/reviews` | Nothing |
| `get_google_performance` | `GET /api/v1/google-performance` | Reputation or Rank on the location |
| `update_profile_fields` | `POST /api/v1/profile-changes` | Owner or admin. Rank or the More Jobs Bundle on the location. |
| `get_profile_change` | `GET /api/v1/profile-changes/{changeId}` | Owner or admin |
| `undo_profile_change` | `POST /api/v1/profile-changes/{changeId}/undo` | Owner or admin |

Each tool takes the fields of its route and gives the same answer. Step 3 shows the routes.

- **Gated tools:** when a location does not have the product a tool needs, the tool answers `product-required` with a `checkoutUrl`. Give the person that link. Never state a price. After the owner pays, call the tool again.
- **Write tools:** `update_profile_fields` changes a real Google Business Profile. Run it with `dryRun: true` first. Show the person the preview. Send the `previewId` only after the person confirms. Without a `previewId`, it refuses with `confirm-required`.
- **No review requests by MCP:** ReviewWheel sends review requests on its own when the job software reports a finished job. The MCP server has no tool that sends or stops one. To connect job software, use an API key (Step 2).
- **Errors:** a refusal is a tool result with `isError: true` and the same `code` as the API errors below. A `401` means the connection is revoked or the person lost access. Ask the person to connect again.

## Step 1: The owner signs up

Give the owner this link: `https://app.reviewwheel.com/start`

The owner must do these things in the browser. You cannot do them for the owner:

- Sign up with an email code or with Google.
- Connect Google and pick the business's Google Business Profile. Every ReviewWheel account connects Google.
- Pick a plan and pay. Stripe takes the payment.

The order of the screens depends on the plan. Let the app lead the owner.

To help the owner choose a plan, read these pages:

- More Jobs Bundle: `https://reviewwheel.com/more-jobs`
- Reputation plans: `https://reviewwheel.com/reputation`
- Rank: `https://reviewwheel.com/rank`
- Website: `https://reviewwheel.com/website`
- Ads: `https://reviewwheel.com/ads`

Read prices from those pages when you need them. Do not repeat a price from memory or from an earlier session.

If the owner already has an account, they sign in at `https://app.reviewwheel.com/sign-in`.

## Step 2: The owner creates an API key

A headless agent uses a ReviewWheel API key. It starts with `rwk_live_`. An owner or an admin creates it on the Webhook connection page:

`https://app.reviewwheel.com/app/connections/webhook`

There are two kinds of key:

| Kind | Scope | `locationId` on each job |
| --- | --- | --- |
| Account key | Every location on the account | Required |
| Location key | One location | Not needed |

Before the first account key, the owner confirms that they have consent to message their customers. Only the owner can give that confirmation. Do not give it for them.

The app shows the key one time. Tell the owner to put it in a secret store or an environment variable, for example `REVIEWWHEEL_API_KEY`. Do not ask the owner to paste the key into the conversation.

Look for the key in this order. Stop at the first one that exists:

1. `REVIEWWHEEL_API_KEY` in your process environment.
2. A project `.env` file that the owner told you to read.

If neither exists, tell the owner to create a key on the page above, set it, and then resume the task.

Do not log the key. Do not show it to the owner. Do not put it in commit messages, error reports or screenshots. In a shell command, use the environment variable, not the value.

## Step 3: Call the API

Send the key as a bearer token. Bodies are JSON. Without an active plan or trial, `job-completed` refuses with `no-plan`. Every other route still answers. A route that needs a product answers `product-required` with a link. A canceled account refuses every route with `no-plan`.

### Check the key

```bash
curl https://api.reviewwheel.com/api/v1/ping \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY"
```

```json
{"ok":true,"keyName":"Agent","kind":"company","companyName":"Example Plumbing","locationName":null}
```

`kind` is `company` for an account key and `location` for a location key.

### List locations

```bash
curl https://api.reviewwheel.com/api/v1/locations \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY"
```

```json
[{"id":"<location id>","name":"Example Plumbing","city":"Atlanta","state":"GA","status":"live"}]
```

Use an `id` from this list as `locationId`.

### Report a completed job

**Warning:** this call can send a review request by text or email to a real customer. Use it only when the owner tells you to, only for a job that is done, and only for a customer who agreed to hear from the business.

```bash
curl -X POST https://api.reviewwheel.com/api/v1/job-completed \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-10482" \
  -d '{
    "locationId": "<location id>",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+14045550123",
    "email": "jane@example.com",
    "jobType": "Water heater install",
    "completedAt": "2026-10-28T15:00:00Z"
  }'
```

| Field | Type | Rule |
| --- | --- | --- |
| `locationId` | string | Required with an account key. Ignored with a location key. |
| `phone` | string | Send `phone`, `email` or both. At least one must be usable. |
| `email` | string | See `phone`. |
| `firstName`, `lastName` | string | Optional. |
| `address` | string | Optional. The job's street address. |
| `jobType` | string | Optional. |
| `completedAt` | ISO 8601 string or epoch number | Optional. When the job was done. |
| `dryRun` | boolean | Optional. `true` runs every check and saves and sends nothing. See below. |
| `previewId` | string | Optional. The `previewId` of a dry run of the same fields, sent to confirm it. See below. |

Send an `Idempotency-Key` header with a stable value for each job, for example your job ID. If you retry the same job with the same key, ReviewWheel does not create it again.

A success looks like this:

```json
{"ok":true,"contactId":"<contact id>","requestId":"<request id>","enrolled":true,"held":null}
```

- `warnings`: present when ReviewWheel dropped a phone or email it could not use. The contact still saves with the other channel.
- `held: "paused"`: the account paused requests. The job saves and waits.
- `deduped: true`: this `Idempotency-Key` was already used. Nothing new happened.
- `stale: true` with `enrolled: false`: the job is too old for a review request.
- `requestId`: the review request this job started, or `null` when it started none. Use it to stop that request.

### Preview a job before you send it

Send the same call with `"dryRun": true`. ReviewWheel runs every check and saves and sends nothing. The answer shows the contact, the location and when each first message is due:

```json
{"ok":true,"dryRun":true,"previewId":"<preview id>","contact":{"existing":false,"firstName":"Jane","lastName":"Doe","phone":"+14045550123","email":"jane@example.com"},"location":{"locationId":"<location id>","name":"Example Plumbing"},"startsRequest":true,"reason":null,"held":null,"sends":[{"channel":"sms","at":"2026-10-28T15:00:00.000Z"}]}
```

- `startsRequest: false`: the job would start no request. `reason` says why.
- `sends[].at`: when that message is due. Messages wait for 8am to 8pm at the location. `null` means held.
- `held: "trial"`: the location is on a trial that holds sends.

Show the preview to the owner. To send it after the owner confirms, repeat the call with the same fields and the `previewId`, within 10 minutes. Your `Idempotency-Key` decides repeats, as on every call. Without one, the `previewId` is the key: one preview sends one job, and a repeat answers `deduped: true`. A changed field refuses with 428 `confirm-required`.

### Stop a review request

```bash
curl -X POST https://api.reviewwheel.com/api/v1/requests/<request id>/stop \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY"
```

```json
{"ok":true,"requestId":"<request id>","result":"stopped"}
```

The request's queued texts and emails are cancelled. The contact, its other requests and the send log stay. A message already sent stays sent. `result` is `already-finished` when nothing was left to send. This needs Reputation on the location.

### Change profile fields

**Warning:** this call changes the business's live Google Business Profile. Use it only when the owner tells you to, and only after the owner confirms the dry run. It needs an account key made by an owner or admin. A location key cannot change profiles.

First run a dry run. Google checks each location and nothing changes:

```bash
curl -X POST https://api.reviewwheel.com/api/v1/profile-changes \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationIds": ["<location id>", "<location id>"],
    "fields": {"specialHours": {"specialHourPeriods": [{"startDate": {"year": 2026, "month": 11, "day": 26}, "closed": true}]}},
    "dryRun": true
  }'
```

```json
{"ok":true,"changeId":"<change id>","previewId":"<change id>","phase":"checking","expiresAt":null,"locations":[{"locationId":"<location id>","name":"Example Plumbing","after":{"specialHours":{"specialHourPeriods":[{"startDate":{"year":2026,"month":11,"day":26},"closed":true}]}},"status":"checking","before":null,"googleCheck":null}]}
```

| Field | Type | Rule |
| --- | --- | --- |
| `locationIds` | list of strings | Required. 1 to 100 `id` values from `/api/v1/locations`. |
| `fields` | object | Required. Google Business Profile Location fields: `categories`, `serviceItems`, `profile`, `regularHours`, `specialHours`, `moreHours`, `serviceArea`, `websiteUri`, `phoneNumbers`. |
| `dryRun` | boolean | `true` checks the change with Google and changes nothing. |
| `previewId` | string | The `previewId` of a dry run of the same body. Without `dryRun`, the call needs it. |

Google checks about 7 locations a minute. Read the change with `GET /api/v1/profile-changes/<change id>` until `phase` is `previewed`. Each location then shows `before`, `after` and `googleCheck`, with `status` `ready` or `refused` and a `code`.

Show the owner each location's before and after. When the owner confirms, repeat the call with the same `locationIds` and `fields`, no `dryRun`, and the `previewId`, before `expiresAt`. Each `ready` location becomes `pending`, then `applied` when Google confirms. A refused location does not change.

- `product-required`: the location needs Rank or the More Jobs Bundle. Give the owner its `checkoutUrl`. Never state a price.
- One profile change runs at a time on an account. A second one gets 409 `company-busy`.

To put every location back:

```bash
curl -X POST https://api.reviewwheel.com/api/v1/profile-changes/<change id>/undo \
  -H "Authorization: Bearer $REVIEWWHEEL_API_KEY"
```

Each location's `undo` reads `pending`, then `applied`. A location reads `refused` with `changed-since` when someone changed the profile after this change: it stays as it is. Call the undo again to see progress and retry what failed.

### Errors

Every error body is `{"ok":false,"code":"<code>","error":"<one sentence>"}`. The errors are grouped by what you do next. Each code has its own anchor on the reference page: `https://reviewwheel.com/api#error-<code>`.

**Fix the key**

| Status | `code` | What to do |
| --- | --- | --- |
| 401 | `invalid-key` | The key is wrong, revoked or missing. Ask the owner to check it or create a new one. Do not retry with the same key. |

**Pick or renew a plan**

| Status | `code` | What to do |
| --- | --- | --- |
| 403 | `no-plan` | The account has no active plan. The owner picks a plan in the app. |
| 403 | `service-ineligible` | That location has no active plan. |
| 403 | `product-required` | That location needs a product it does not have. Give the owner the `checkoutUrl` from the error body. Never state a price. A null `checkoutUrl` means the location is paused: the owner resumes it in the app. |

**Ask the owner**

| Status | `code` | What to do |
| --- | --- | --- |
| 403 | `consent-required` | The owner must confirm in the app that they have consent to message their customers. |
| 403 | `approver-required` | Profile changes need an account key made by an owner or admin. The owner creates one. |
| 409 | `source-conflict` | Another job source is connected for that location. The owner disconnects it in the app first. |
| 428 | `confirm-required` | Run the call with `dryRun: true`, show the owner the preview, then send its `previewId` with the same fields within 10 minutes. |

**Fix the request**

| Status | `code` | What to do |
| --- | --- | --- |
| 400 | `invalid-body` | Send a JSON object. |
| 404 | `location-unknown` | `locationId` is not on this account. Call `/api/v1/locations`. |
| 422 | `invalid-field` | Fix the field that `error` names. |
| 422 | `location-required` | An account key needs `locationId` on each job. |
| 422 | `no-contact` | Send a usable `phone` or `email`. |
| 404 | `request-unknown` | That `requestId` is not on this account. Use the `requestId` that `job-completed` returned. |
| 404 | `not-found` | No route matches the path. Check it against `openapi.json`. |
| 404 | `change-not-found` | That `changeId` is not on this account. Use the `changeId` that `profile-changes` returned. |
| 409 | `not-applied` | The change was never applied, so it has nothing to undo. |
| 422 | `invalid-change` | Send 1 to 100 locations and only the fields that `error` lists. |
| 403 | `source-blocked` | `completedAt` is missing, or it is earlier than the location's last job source change. Send `completedAt` for jobs finished after that change. |

**Wait and retry**

| Status | `code` | What to do |
| --- | --- | --- |
| 429 | `rate-limited` | Wait the number of seconds in `Retry-After`, then retry. |
| 409 | `company-busy` | Another profile change on this account is still running. Wait the number of seconds in `Retry-After`, then retry. |
| 503 | `provider-state-changed` | Try again later. |
| 503 | `no-template` | Try again later. |

## What the API cannot do today

The API cannot create an account, add a location, change a plan, take a payment, or reply to reviews. It changes only the Google Business Profile fields listed above. The owner does these things in the app.

## Revocation

The owner revokes a key on the same Webhook connection page. A `401` on a key that worked before means the key is revoked. Drop it and ask the owner for a new one through the same secret store.

An MCP connection is revoked on the Agents tab of `https://app.reviewwheel.com/app/connections`. A person revokes their own connection. An owner or admin can revoke any connection on the account. The next call gets `401`.

## Help and terms

- Support: `support@reviewwheel.com`
- Terms: `https://reviewwheel.com/terms`
- Privacy: `https://reviewwheel.com/privacy`
- Acceptable use: `https://reviewwheel.com/acceptable-use`
