Implement and test referral tracking with Codex
A repository change you can review: map the trusted backend, implement one signup flow, and produce evidence for retry and secret-isolation behavior.
RefRef technical guide · Reviewed against source and official client documentation on 3 October 2026 · Review preview
Prerequisites
- Codex CLI installed and authenticated, with the application repository available locally.
- A configured RefRef MCP endpoint and a Console account; Workspace owner/admin authority is required for configuration.
- A Sandbox Project, published Program configuration, a test database and the app’s existing test runner.
- A stable application identity and server-only credentials configured outside prompts. Select individual or group identity before implementation.
Keep the MCP setup reference and application integration contract open. Configuration and runtime tracking are separate steps.
1. Register the HTTP server
Set REFREF_MCP_URL to the exact operator-provided resource URL ending in /mcp. Review OAuth consent in your browser. Read-only discovery needs mcp:read; this configuration walkthrough also requests mcp:configure. offline_access allows refresh.
codex mcp add refref --url "$REFREF_MCP_URL"
codex mcp login refref --scopes mcp:read,mcp:configure,offline_access
codex mcp list2. Write an integration map before code
Open Codex in the application checkout, inspect /mcp, and provide the two canonical references below. This prompt produces a file-level plan and a reproducible acceptance target.
Read the repository instructions and git status. Use RefRef get_workflow with workflow="integration". Discover Workspaces and Projects and ask me to confirm one Sandbox Project. Map signup, session identity, same-origin capture, billing evidence and retry storage to actual files. Propose the smallest signup-only change and tests. Identify missing backend infrastructure. Preserve unrelated changes. Do not change dependencies, deploy, or use Live data.3. Keep configuration review separate
If the Program needs configuration, retrieve the configuration workflow and prepare preview_change with explicit choices. Inspect and approve the returned reviewUrl in the Console. Ask Codex to execute only that approved proposal. Retry its same ID after an uncertain response; do not create a replacement merely because the response was lost.
4. Implement a durable retry boundary
After reviewing the map, use this implementation prompt. The retry case is the central artifact: an identical business operation must keep its initial evidence even if the browser receives a newer touch.
Implement the agreed signup-only integration. Read the current API schema rather than guessing payloads. Persist a retry record containing the original signup fact and first context evidence snapshot before delivery. Re-sign that same snapshot when its authorization expires. Do not read a newer browser journal on retry. Add a failing-then-passing test for response loss after acceptance, and a test for a later touch arriving before retry. Assert one canonical Event and the original attribution. Report exact commands/results and any checks that could not run.5. Review the diff and test evidence
Inspect the generated patch for server-only secrets, authenticated identity, Project scope and an honest pending state. Run the application’s focused tests, then exercise a referral link in two browser sessions. Disconnect the OAuth client from the auth app’s connections page after testing; reconnecting requires new proposals. This does not remove the application’s separate backend integration.
The lost-response test, worked through
This synthetic timeline defines a test fixture for your app’s retry store. The labels below describe local application state, not an API request body.
01
Attempt 1 · revision 7
Store signup:user-b, its original occurredAt, and evidence snapshot revision 7. RefRef accepts the Event, but your backend loses the response.
02
Another arrival · revision 8
The browser captures a later touch. Its current journal advances to revision 8. The stored signup delivery must stay pinned to revision 7.
03
Retry · still revision 7
Re-sign the retained snapshot if needed and resend the original fact. Assert the same Event ID and attribution result. A deliberate revision-8 replay must surface FACTS_CONFLICT.
Record actual results beside these checks
- CHECK 01Simulate loss of the first accepted signup response.
- Expected resultRetry uses the same fact identity and original evidence; the accepted Event ID remains the same.
- CHECK 02Capture a different arrival before redelivering the old signup.
- Expected resultThe retry uses its stored evidence, not the new journal. A changed-evidence conflict is surfaced rather than silently reassigned.
- CHECK 03Inspect browser requests and built client assets.
- Expected resultNo Workspace API key or Project signing secret appears; the browser calls its own capture backend.
- CHECK 04Disconnect the MCP client, then attempt another management read.
- Expected resultThe old grant no longer authorizes access. Configuration requires reconnecting; old proposals are not revived.
An earned Reward is an accounting result. It does not establish that cash, credit or a discount was delivered.
What has actually been validated
RefRef’s repository status records actual Codex CLI OAuth, discovery, Sandbox/Live reads, preview and pre-approval rejection against disposable local fixtures. Installed CLI login help was checked for --scopes during this review. The generated-app retry exercise is an acceptance procedure, not a claim that a Codex-authored application was tested in this session.