# StrollPlace auth.md

This guide tells AI agents how to register a StrollPlace account on behalf of
a user. Ask which account the user needs before starting.

## Agent registration

### Registration endpoint

POST https://strollplace.com/api/mcp

For My StrollPlace, call `begin_registration` over MCP without credentials.
This prepares a user-claimed registration and issues a bearer token scoped
to that registration. It creates no account and sends no email.

```yaml
register_uri: https://strollplace.com/api/mcp
registration_method: anonymous
registration_tool: begin_registration
claim_uri: <approvalUrl>
credential_type: bearer
credential_field: registrationToken
```

Replace <approvalUrl> with the URL from the MCP tool result.
The user opens the returned `approvalUrl` in their browser to approve the
registration. Approval sends a six-digit code to the email they enter.

## Supported registration methods

- **My consumer account — anonymous start, then verified email.** See the
  MCP registration and user approval steps below.
- **Pro professional account — invitation.** After the user approves agent
  setup from their invitation, send `POST https://pro.strollplace.com/api/auth/agent-setup` with
  their one-time setup token as a Bearer token.
- **HQ business or network account — verified email.** After the user requests
  agent verification during signup, send `POST https://hq.strollplace.com/api/auth/agent-verify-email`
  with their one-time email verification token as a Bearer token.

## Register a My StrollPlace consumer account

Connect to [StrollPlace MCP](https://strollplace.com/api/mcp) using Streamable HTTP. Initialize
the connection and use `tools/list` to read the registration tool schemas.
Send this JSON-RPC request with the negotiated MCP protocol version and a fresh
UUID as `idempotencyKey`.

```http
POST /api/mcp HTTP/1.1
Host: strollplace.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "begin_registration",
    "arguments": {
      "agentName": "Example agent",
      "idempotencyKey": "<fresh UUID>"
    }
  }
}
```

Read the following fields from the MCP result's `structuredContent`:

```json
{
  "registrationId": "<registration ID>",
  "approvalUrl": "<user approval URL>",
  "registrationToken": "<one-time registration bearer token>",
  "expiresAt": "<expiration time>"
}
```

### Claim and complete registration

1. Give the user only the approvalUrl. Ask them to enter their email address,
   review the Terms of Use and Privacy Policy, and approve this registration.
   Approval sends the first verification email.
2. Present the registrationToken as `Authorization: Bearer <registrationToken>`
   on subsequent registration requests. Keep the token in your client's secret
   configuration and out of URLs and messages. Use get_registration_status
   with registrationId to check for approval.
3. After approval, get the six-digit code from the user or an inbox they have
   authorized you to access. Call complete_registration with registrationId and
   code. Use request_registration_email if the user needs a new code.
4. Wait for a registered receipt before reporting success. Reuse the same
   registrationId when retrying completion. The user signs in to My StrollPlace
   after registration.

### Credential scope and recovery

The Bearer credential is scoped to a single registration and expires within
30 minutes. The user can revoke the approval in their browser, or the agent
can call cancel_registration before completion. Start a fresh registration and
obtain fresh approval if the token is lost or the registration expires.

## Pro professional account

Call get_registration_link with accountType set to pro. Share the [Pro
application page](https://pro.strollplace.com/apply) with the person so they can complete the
application in their browser. Eligibility and invitation requirements depend
on the market and professional category. If the person already has a private
invitation link, they can use it directly.

On the invitation page, the person reviews the agreements, sets their
password if needed, and chooses to let their AI agent finish accepting the
invitation. POST to [Pro registration completion](https://pro.strollplace.com/api/auth/agent-setup)
with the one-time setup token they share. The token expires in ten minutes.
The person signs in separately after completion.

```http
POST /api/auth/agent-setup HTTP/1.1
Host: pro.strollplace.com
Authorization: Bearer <setupToken>
Content-Length: 0
```

## HQ business or network account

Call get_registration_link with accountType set to hq. Share the [HQ signup
page](https://hq.strollplace.com/signup) with the person so they can choose a business or network
account, review the agreements and set their password. If they choose to
let their AI agent finish verification, HQ emails them a one-time token.
POST to [HQ registration completion](https://hq.strollplace.com/api/auth/agent-verify-email) with the
token they share. The token expires in 30 minutes.
The person can also use the email link to verify directly and then sign in.
Existing Pro users can sign in to HQ with their own credentials.

```http
POST /api/auth/agent-verify-email HTTP/1.1
Host: hq.strollplace.com
Authorization: Bearer <verificationToken>
Content-Length: 0
```

For Pro and HQ, send the Bearer token with an empty request body. A successful
response contains status registered. Keep tokens out of URLs and logs, and
use the client's private credential channel to handle them.

## Sign in after registration

Send the user to [My StrollPlace sign-in](https://my.strollplace.com/sign-in),
[Pro sign-in](https://pro.strollplace.com/login), or
[HQ sign-in](https://hq.strollplace.com/login). Existing users go straight
to sign-in. Registration tokens cannot sign in or authorize contact requests.
The user grants agent access for contact requests separately in My Settings.

See the [StrollPlace agent guide](https://strollplace.com/agents) for connection and approval details.
