Reference
Customer Agent Integrations
Learn how approved customer agents and technical partners should use HotRoute service-account access while respecting staff authority.
Overview / Purpose
Customer agents can help staff inspect product docs, retrieve visible football context, summarize cited information, and prepare controlled downstream work.
They should not become a second source of authority. A customer agent must use the same governed access path an approved integration uses, and it must respect service-account scope, staff authority, plan access, lifecycle state, rate limits, and safe refusal behavior.
Use this page before connecting Codex, Claude, ChatGPT, MCP, hotroute-tools, or a similar tool to HotRoute.
Who this is for
This page is for organization owners, football operations leads, analysts, and approved technical partners.
In football terms, this is for the person deciding whether an outside agent should help a staff search docs, cite playbook context, retrieve schedule information, render a callsheet, or prepare a controlled workflow without taking over coaching judgment.
What to know first
Agent access is scoped access. The owner decides which organization, team, season, object families, and operation classes the tool can use.
Agent answers should be citation-first. A good response should show whether it used product docs, visible customer football canon, or both.
An agent may help retrieve, search, explain, draft suggestions, or prepare work where an approved route supports that job. It must not review, publish, archive, manage billing, manage members, rotate service-account keys, or act as a support or platform administrator.
Some agent workflows are live only for approved service-account API use. Some are private-preview. Some are planned. Do not treat planned behavior as generally available.
Current posture by integration type
| Integration type | Current customer posture | What it can do when approved | What it must not do |
|---|---|---|---|
| Service-account API client | Live where the owner has created a scoped service account and the route is available. | Call governed /api/v1 routes inside the selected scope. | Use the key as a staff login, request hidden objects, or work outside service-account scope. |
| Product-doc search agent | Beta where product-doc search is enabled for approved authenticated or service-account contexts. | Retrieve customer-safe HotRoute docs citations and explain product concepts. | Treat product docs as customer-private football truth or infer hidden customer objects. |
| Customer-private semantic search agent | Beta or private-preview depending on the customer's add-on, credit, scope, and route approval. | Search visible private football canon and return cited refs when every gate passes. | Search private canon without plan/add-on/credit/scope authority, or return uncited hidden snippets. |
| Codex, Claude, or ChatGPT custom workflow | Private-preview unless HotRoute and the customer approve the exact service-account setup. | Use a scoped service-account key to call approved API routes and summarize cited results. | Store raw keys insecurely, call unapproved routes, or present suggestions as staff-approved truth. |
| MCP adapter | Private-preview or planned unless a specific adapter has been approved. | Act as a thin adapter over governed HotRoute routes. | Use unapproved access paths, hold broad credentials, or make customer-visible calls outside governed routes. |
hot CLI from hotroute-tools | Live for approved service-account API use where the owner has created a scoped key and installed the signed CLI artifact. | Help approved operators and agents inspect resource metadata, retrieve governed records, run supported searches, and send contract-backed writes. | Ship a customer mutation before the HotRoute API route exists and rejects wrong org, missing scope, hidden object, entitlement, lifecycle, and rate-limit states. |
| User-delegated OAuth agent | Planned. | Future user-consented access when OAuth, token, consent, revocation, and audit behavior are approved. | Borrow API-key service-account access and pretend it represents an individual coach. |
Configuration posture
Exact setup steps for customer agents will be published when each integration path has an approved user workflow.
For now, treat this page as posture guidance. Do not configure Codex, Claude, ChatGPT, MCP, hotroute-tools, or another agent-style tool unless HotRoute and the organization owner have approved the exact service account, scope, storage location, and route family the tool will use.
What good looks like
A healthy customer-agent workflow feels like a careful staff assistant, not an autonomous coach.
The agent should:
- name the source it used
- distinguish product docs from private football canon
- include useful citations or object refs
- ask for missing team, season, playbook, or object scope instead of guessing
- refuse when scope, plan, lifecycle, or rate limits do not allow the request
- route final football judgment back to the staff
- keep the service-account key narrow and revocable
Common questions or mistakes
Can an agent use product docs to answer questions about our private playbook?
No. Product docs explain HotRoute behavior. Private football questions need private-canon access, approved scope, and cited visible objects.
Can an agent publish changes for us?
No. Customer-agent access does not grant review, approval, publish, archive, billing, membership, support-admin, or platform-admin authority.
Can an MCP adapter use another access path?
Customer-visible adapters should call governed /api/v1 routes or another approved customer access path. Unpublished commands are not the customer access path.
Can hotroute-tools add a mutation before the API route exists?
No. The governed HotRoute API contract is the source of truth. A CLI command should not expose planned mutation behavior before the API route exists and enforces the right organization, scope, entitlement, lifecycle, and safe-error checks.
What should an agent do when HotRoute refuses a request?
It should report the refusal category plainly, avoid guessing hidden state, and ask the owner or staff operator to adjust scope only when broader access is appropriate.
Related docs / next steps
Start with Manage Service Accounts to create, review, revoke, or delete scoped keys.
Use Install the hot CLI when the approved agent will connect through the HotRoute command-line tool.
Use External API to understand which resource families an approved service account can call.
Use Retrieval and Search to understand how cited product-doc and private-canon answers should behave.