--- title: "FieldRobin signup and onboarding guide" description: "The public, machine-readable signup contract for FieldRobin account creation and onboarding." canonical_url: https://fieldrobin.com/register markdown_url: https://fieldrobin.com/signup.md content_type: signup_guide product: "FieldRobin" company: "Doorkeeper Labs LLC" updated_at: 2026-09-22 language: en --- # FieldRobin signup and onboarding guide Use this guide to explain or integrate the FieldRobin account-creation flow. Creating an account is a consequential action: an agent must get the person's explicit approval before submitting the registration request and must collect the password directly from the person. Never invent credentials or submit a form silently. ## Discovery - Signup alias: https://fieldrobin.com/signup (redirects to the canonical browser page at https://fieldrobin.com/register) - Canonical browser page: https://fieldrobin.com/register - Machine-readable flow: https://fieldrobin.com/.well-known/signup.json - OpenAPI document: https://fieldrobin.com/openapi.json - API base URL: https://fieldrobin.com/api/v1 ## 1. Check registration mode Call `GET https://fieldrobin.com/api/v1/auth/registration` without authentication. The response says whether public registration is open and includes the signup, documentation, manifest, onboarding, and verification paths. When `registration_open` is `true`, continue to account creation. When it is `false`, the flow is invite-only: use an approved `invite_token`, or direct the person to the access-request page. The server remains the authority; do not assume the mode from cached page content. ## 2. Create the account Send `POST https://fieldrobin.com/api/v1/register` over HTTPS with `Content-Type: application/json` and `Accept: application/json`. Required JSON fields: - `email`: valid email address, up to 255 characters. - `password`: at least 8 characters. - `password_confirmation`: exactly the same value as `password`. Optional JSON fields: - `name`: display name. If omitted or empty, FieldRobin uses the email address before `@`. - `business_name`: business name, up to 255 characters. - `trade_type`: trade or service type, up to 100 characters. - `plan`: `free`, `pro`, or `team`. It defaults to `free`; paid plans start the configured local trial and report `trial_started: true`. - `invite_token`: exactly 64 characters and required for invite-only registration. A valid approved invite verifies the email automatically. - `include_token`: set to `true` only for a declared native client. - `turnstile_token` or `cf-turnstile-response`: browser bot-protection response when the server requires it. Do not send the browser honeypot field `website`. Do not send a password, invite token, or Turnstile secret in a URL, log, or `Idempotency-Key`. ### Browser request ```http POST https://fieldrobin.com/api/v1/register Accept: application/json Content-Type: application/json Idempotency-Key: 8f2e4d71-1ec6-4ed1-9fc3-4a9c1e8b6f20 { "email": "person@example.com", "password": "", "password_confirmation": "", "plan": "free" } ``` Browser registration sets an HttpOnly authentication cookie. A browser response does not include a plain token, even if `include_token` is supplied without a declared native client. ### Native request Native clients must send `X-FieldRobin-Client: ios` or `X-FieldRobin-Client: android` and may set `include_token: true` to receive a bearer token. These headers identify the routing mode; they are not device attestation. Rate limits, email verification, and account protections still apply. ## 3. Handle the successful response A successful response has status `201` and includes: - `user`: the newly created account summary. - `selected_plan`: the selected plan key. - `trial_started`: whether a paid-plan trial started. - `email_verification_required`: whether the person must verify the email address. - `token`: only for native clients that declare the native client header and request `include_token`. For browser signup, continue to `/app/onboarding`. Unverified users may save onboarding progress. If verification is still required after onboarding, the application sends the person to `/app/verify-email` before allowing access to protected workspace data. Invite registrations normally set `email_verification_required` to `false` because the approved invite has already verified the address. ## Onboarding API After authentication, `GET https://fieldrobin.com/api/v1/onboarding` returns the current flow state. It includes `state`, `flow.step_ids`, `flow.current_step_id`, prefilled business information, available capabilities, the selected goals, activation information, and a first-win preview. Use `POST https://fieldrobin.com/api/v1/onboarding` with `action: draft` to save progress or `action: complete` to finish setup. Completion requires a goal for every user and, for owners, a business name, trade, and service area. Send only the fields the person approved. The onboarding API is authenticated and tenant-scoped; it must not be treated as a public account-discovery endpoint. The first-win preview is informational until the person completes setup. A `requires_approval` value in the preview does not authorize an external action. ## Retry and error behavior `Idempotency-Key` is optional for registration. Use one new, high-entropy key per signup attempt and reuse it only when retrying the same request after a timeout or lost response. - Same key and equivalent request: the original `201` result is replayed, with `Idempotency-Replayed: true`. - Same key and different request: `409 IDEMPOTENCY_KEY_REUSED`; use a new key only for a new approved attempt. - Same key while the first request is running: `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` with `Retry-After`; wait and retry the same request. - A validation, bot-protection, closed-registration, or invalid-invite failure does not permanently reserve the key; correct the request and retry. Common responses: - `403 REGISTRATION_CLOSED`: an invite is required. - `403 INVITE_INVALID`: the invite is expired, already used, or does not match the email. - `422`: field validation, password mismatch, or Turnstile failure. - `429`: registration rate limit; honor `Retry-After` and do not create a new key just to bypass throttling. ## Security rules Use HTTPS in production. Keep passwords and invite tokens in memory only as long as necessary. Never log request bodies, credentials, invite tokens, Turnstile responses, authentication cookies, bearer tokens, or raw idempotency keys. Require explicit user approval immediately before account creation and before any onboarding action that creates starter data or sends an external message. - [Canonical registration page](https://fieldrobin.com/register) - [Signup flow manifest](https://fieldrobin.com/.well-known/signup.json) - [OpenAPI 3.1](https://fieldrobin.com/openapi.json) - [Pricing](https://fieldrobin.com/pricing) - [Developer resources](https://fieldrobin.com/developers)