Connect Tokens Guide

Connect FlatRate Pro and ShopOS to Any Platform

Connect Tokens are the optional AI add-on for customers who want to use FlatRate Pro or ShopOS data with ChatGPT, Claude, MCP servers, Zapier, or custom applications. This guide covers connecting your preferred platform using per-user Connect Tokens.

Supported Platforms

What you'll get

• Per-user auth via Connect Token (no API key sharing)
• 12 endpoints covering profile, jobs, notes, tools, timer, DTC lookup
• Voice Agent parity: everything the voice agent can do, the API can do
• Real-time sync with your FlatRate Pro data

Prerequisites

• A FlatRate Pro account or ShopOS organization with Connect Token access
• Firebase project deployed with Functions and Hosting for this repo
• Deployed Cloud Function: gptActionsHttp and Hosting rewrite for /api/gpt/**

1) Create your Connect Token

1. Open Connect GPT.
2. Sign in.
3. Click "Create token". Copy it immediately.
4. You can revoke the token later on the same page.

2) Available API Endpoints

The public FlatRate Pro endpoint is intentionally narrow. All supported endpoints require the X-User-Token header except /api/gpt/health. It includes one explicit write for structured job logging.

Core Endpoints

Structured Job Logging

Grounded Lookup Tools

3) Platform Setup Guides

Option A – ChatGPT Custom GPT Action

In ChatGPT → Create a GPT → Configure → Actions:

1. API Base URL: https://geargenius.ai (or your Firebase Hosting domain)
2. Import OpenAPI schema:
   • URL: https://geargenius.ai/.well-known/frp-gpt-openapi.json
3. Authentication: API Key, Header name: X-User-Token, leave value blank
4. Users paste their token when first using the GPT

Option B – ChatGPT Connector (Teams & Enterprise)

1. Open ChatGPT workspace → Connectors → Add Connector
2. Paste manifest URL: https://geargenius.ai/.well-known/frp-connector-manifest.json
3. Leave credential field blank so each user pastes their own token
4. The connector shows the focused technician assistant surface and privacy links

Option C – Claude Projects (Anthropic)

1. Create a Connect Token at Connect GPT (label: "claude")
2. In Claude Project settings, add an API integration
3. Configure HTTP requests with:
   • Base URL: https://geargenius.ai/api/gpt
   • Header: X-User-Token: <your-token>
4. Claude can now call the public technician profile, structured job logging, stats, estimate, and lookup endpoints

Option D – MCP Server (Model Context Protocol)

1. Create a Connect Token (label: "mcp")
2. Configure your MCP server with tools pointing to our endpoints:

{
  "baseUrl": "https://geargenius.ai/api/gpt",
  "headers": { "X-User-Token": "<your-token>" }
}

3. Map endpoints to MCP tools for profile, recent jobs, structured job logging, stats, estimate, DTC, and vehicle lookup

Option E – Zapier / Make / n8n

1. Create a Connect Token (label: "zapier" or "make")
2. Use the Webhooks by Zapier or HTTP module
3. Configure:
   • URL: https://geargenius.ai/api/gpt/user/jobs/recent
   • Headers: X-User-Token: <your-token>
4. Trigger on schedule or connect to other apps

Option F – LangChain / AI Agents

1. Create a Connect Token (label: "agent")
2. Configure API tool with requests library:

import requests

headers = {"X-User-Token": "your-token"}
response = requests.get(
    "https://geargenius.ai/api/gpt/user/profile",
    headers=headers
)

3. Wrap endpoints as LangChain tools

Option G – Custom REST Integration

Use any HTTP client with the X-User-Token header:

curl -H "X-User-Token: YOUR_TOKEN" \
  https://geargenius.ai/api/gpt/user/stats

curl -X POST -H "X-User-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jobName":"Oil change","actualHours":0.5}' \
  https://geargenius.ai/api/gpt/user/jobs

Recommended System Instructions

Copy and paste these instructions into your Custom GPT "Instructions" field or your Agent's system prompt to ensure it uses the tools correctly.

4) Configure Authentication (per-user)

Use a header-based API key:

• Type: API Key
• Auth Type: Custom (or Bearer – see note below)
• Custom header name: X-User-Token
• API Key value:
  • Leave blank in the builder if you want each user to paste their own token at first use (recommended)
  • For private testing only, you can paste a token; clear it before sharing the GPT

5) Test the connection

From a terminal (replace TOKEN and HOST):

# Health
curl -sS -H "X-User-Token: TOKEN" https://<HOST>/api/gpt/health | jq

# Profile summary
curl -sS -H "X-User-Token: TOKEN" https://<HOST>/api/gpt/user/profile | jq

# Recent jobs
curl -sS -H "X-User-Token: TOKEN" "https://<HOST>/api/gpt/user/jobs/recent?limit=3" | jq

# Quick stats (today, week, or month)
curl -sS -H "X-User-Token: TOKEN" "https://<HOST>/api/gpt/user/stats?range=week" | jq

# Structured job log creation
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"jobName":"Brake pad swap","category":"Brakes","flatRateHours":1.5,"actualHours":1.2,"vehicle":{"year":2019,"make":"Honda","model":"Accord"}}' \
  https://<HOST>/api/gpt/user/jobs | jq

# Get time estimate
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"jobDescription":"Replace water pump on 2018 Honda Accord"}' \
  https://<HOST>/api/gpt/user/estimate | jq

# DTC lookup
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"code":"P0420","make":"Toyota","model":"Camry","year":"2019"}' \
  https://<HOST>/api/gpt/tools/dtc | jq

# Search by vehicle
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"query":"Honda Civic"}' \
  https://<HOST>/api/gpt/vehicle/lookup | jq

        

6) Endpoint Details

Refer to the OpenAPI Schema for full details on all available endpoints and request/response formats.

7) Rate limits and safety

• Per-user rate limiting is enforced server-side; excessive calls return HTTP 429.
• Endpoints avoid returning credentials or sensitive PII.
• The public endpoint is grounded and allows one explicit write for structured job logging.
• All other write actions stay in the FlatRate Pro app.

8) Troubleshooting