# InfluTo for AI agents — connect, tools, REST

> InfluTo is a referral & affiliate ATTRIBUTION platform for mobile apps (iOS, Android,
> React Native, Flutter). A developer creates an app + campaign at https://influ.to, drops in
> one of four native SDKs, initializes with an API key, and InfluTo attributes installs and
> validates in-app purchases to influencer referral codes — via either RevenueCat (webhook)
> or store-direct (Apple App Store Server API / Google Play service account).
> This page is the control-plane reference: how an AI agent connects to InfluTo, what it may do
> (scopes), every MCP tool, and the /api/agent/* REST surface behind them.

## Connect (OAuth 2.1 — one command, no keys)

The InfluTo MCP server lives at **https://influ.to/mcp** (Streamable HTTP).

- **Claude Code:** `claude mcp add --transport http influto https://influ.to/mcp`
- **claude.ai (web / desktop):** Settings → Connectors → Add custom connector → https://influ.to/mcp
- **Codex CLI:** `codex mcp add influto --url https://influ.to/mcp`
- **Cursor / any MCP client:** add `https://influ.to/mcp` as an HTTP (streamable) MCP server — Settings → MCP → Add server → { "influto": { "url": "https://influ.to/mcp" } }

On the agent's first InfluTo call your browser opens an InfluTo consent page —
sign in (or sign up), pick the organization the agent may act on, review the scopes, click
Approve. Done: the client stores the OAuth grant and refreshes it automatically. Revoke any
time at https://influ.to/dashboard/connect-agent (Connected agents).

Headless / CI fallback: mint an `it_mcp_*` agent key at
https://influ.to/dashboard/connect-agent (shown once) and send it as
`Authorization: Bearer $INFLUTO_API_KEY` — same MCP URL, same REST surface, same scopes.

## Auth model

- **OAuth 2.1 (primary):** discovery + dynamic client registration + PKCE browser consent with an
  organization picker. Access tokens live ≤1h and refresh automatically; revoking the grant on the
  dashboard kills refresh immediately (the current token dies within the hour).
- **Agent keys `it_mcp_*` (CI fallback):** minted on https://influ.to/dashboard/connect-agent,
  shown once, revocable, same scopes.
- Both principals hit the same org-scoped guards: a missing scope is a **403**, a cross-tenant id
  is a **404** (never a 403 — no existence oracle).
- The dashboard's own REST (`/api/apps/*`, `/api/campaigns/*` — no `/agent/`) is
  session-JWT only. **An API key there gets 401 by design** — agents always use `/api/agent/*`.

## Scopes

| Scope | Grants |
|---|---|
| `apps:read` | List and inspect your apps and their integration status |
| `apps:write` | Create and update apps (names, links, creator-code settings) |
| `campaigns:read` | View campaigns, milestones and settings |
| `campaigns:write` | Create and update campaigns, bonuses, and their status |
| `analytics:read` | Read clicks, installs, trials, conversions and revenue analytics |
| `creators:read` | List creators, invitations and access codes |
| `creators:write` | Invite creators and create free-access codes |
| `assets:read` | List marketing assets and content examples |
| `assets:write` | Feature/unfeature assets (uploads stay in the dashboard) |
| `billing:read` | See wallet balance and auto-recharge status (read-only) |
| `integration:verify` | Run integration checks and sandbox test events |

New keys and OAuth consents default to all of the above. Hard-denied to every agent, regardless of grant: money writes
(top-ups, transfers), payouts, raw credentials, deletes, and admin. Secrets and money move only
through signed, short-TTL dashboard deep-links the HUMAN opens (top-up, credential upload,
asset upload) — they never transit the agent.

## MCP tools (57)

The live, always-in-sync catalog is the MCP resource `influto://tools` (the server generates it
from its registered tools at read time). Reference bulk lives in resources too:
`influto://contract` (the wire contract) and `influto://sdk/{platform}` (per-SDK reference).

### Discovery (4)

Pure lookups — which SDK, which validation path, which invariant.

- `influto_list_sdks` — The four SDKs with package id, registry, repo and current version.
- `influto_recommend_sdk` — Free-text stack ('expo', 'swiftui', 'kotlin', …) → the ONE SDK + peer deps.
- `influto_recommend_validation` — Pick the ONE validation path: RevenueCat webhook vs store-direct (never both).
- `influto_explain_contract` — Wire-contract invariants per topic: attribution, purchase, comp, dedup, rc-attributes.

### Scaffold (6)

Version-correct code snippets straight from the SDK registry.

- `influto_scaffold_install` — Install command(s) + peer dependencies for an SDK.
- `influto_scaffold_init` — The one-time initialize() snippet (THROWS on failure — surface it).
- `influto_scaffold_attribution` — The checkAttribution() launch snippet.
- `influto_scaffold_manual_code` — Optional manual referral-code entry / ReferralCodeInput snippet.
- `influto_scaffold_report_purchase` — Store-direct purchase-reporting snippet (skip on the RevenueCat path).
- `influto_scaffold_full` — One call → the exact ordered integration steps for a stack + validation path.

### Provision (7)

Stand up the account side: org → app (+ API key) → campaign.

- `influto_whoami` — The developer + organizations behind the connected agent.
- `influto_create_org` — Create an organization (only when whoami shows none).
- `influto_search_store` — Search the App Store + Google Play for an app's store identifiers.
- `influto_scrape_store` — Scrape store metadata incl. the numeric Apple app_store_id.
- `influto_check_slug` — Is an app slug free? (Slugs are globally unique — first segment of referral URLs.)
- `influto_provision` — Org → app (+ API key + webhook secret) → campaign → activate, in one idempotent call.
- `influto_regenerate_webhook_secret` — Rotate the RevenueCat webhook secret (returned once).

### Configure (7)

Wire the purchase-validation path; secrets go through signed deep-links.

- `influto_get_validation_status` — Per-platform validation config + what's missing (non-secret).
- `influto_setup_revenuecat` — The webhook URL + the two subscriber attributes to wire RevenueCat.
- `influto_get_credential_upload_link` — Signed deep-link the HUMAN opens to upload credentials — secrets never transit the agent.
- `influto_set_apple_meta` — Non-secret Apple identifiers: Issuer ID, Key ID, environment, App Store ID.
- `influto_validate_store_credentials` — Run the live credential green-check (loop while retryable).
- `influto_activate_store_direct` — Flip a platform to store-direct once the green-check passed.
- `influto_recommend_validation_for_platforms` — Which path to wire and what it needs (configure-flow reminder).

### Verify (4)

The differentiator: prove a real ATTRIBUTED conversion happened.

- `influto_integration_status` — THE verify rollup: {live, checklist[], attributed_conversion_count, campaign health, …}.
- `influto_recent_events` — Recent SDK events + purchase webhooks with attribution flags (SANDBOX/PRODUCTION filter).
- `influto_test_integration` — Fire a SANDBOX INITIAL_PURCHASE through the real attribution pipeline.
- `influto_verify_user_conversions` — Did a specific app_user_id's purchases attribute?

### Operate (14)

Run the program: apps, campaigns (milestone bonuses + i18n), awards, analytics.

- `influto_list_apps` — Every app across the developer's orgs, with canonical click totals.
- `influto_get_app` — Full app detail incl. *_i18n maps, support_email and creator-code settings.
- `influto_update_app` — Update whitelisted app settings (i18n dicts merge; credentials excluded).
- `influto_list_campaigns` — Campaigns by app/status with canonical clicks + milestone counts.
- `influto_get_campaign` — Full campaign: commission, bonus_rules, i18n copy, stats.
- `influto_create_campaign` — Full-featured create incl. milestone bonus_rules + i18n (created as DRAFT).
- `influto_update_campaign` — Update a campaign — same surface as create.
- `influto_set_campaign_status` — Activate/pause; activation enforces wallet escrow (402 → top-up deep-link).
- `influto_list_bonus_awards` — Milestone awards with creator identity + live fraud-aware progress.
- `influto_review_bonus_award` — Approve or void an earned milestone award (pre-payout only).
- `influto_get_analytics_overview` — Per-app period rollup: canonical clicks (+ decomposition), installs, trials, conversions, revenue, commission.
- `influto_get_campaign_funnel` — Clicks → installs → trials → paid with step rates (find the leak).
- `influto_list_top_affiliates` — Top creators by period revenue for an app or campaign.
- `influto_get_daily_performance` — Zero-filled daily series for trend checks and charts.

### Grow (15)

Recruit and reward creators; read-only wallet visibility; the doctor.

- `influto_list_affiliates` — Every creator in a campaign: codes, canonical clicks, earnings, milestone progress, INFLU- code state.
- `influto_invite_creator` — Invite one creator by email (localized invitation + personal message; optional custom commission).
- `influto_invite_creators_batch` — Bulk-invite from a list/CSV — live capacity accounting, per-item results, partial success.
- `influto_withdraw_invitation` — Withdraw a PENDING invite (frees a marketplace capacity slot).
- `influto_get_join_link` — The shareable public join-page URL (?lang=xx, OG card) + readiness warnings.
- `influto_list_invitations` — Invitation states across campaigns (default: still pending).
- `influto_list_free_codes` — Free-access codes incl. platform-issued INFLU- creator codes + redemption state.
- `influto_create_free_code` — Mint a comp/free-access code (ambassadors, press, VIPs) — no purchase needed.
- `influto_list_assets` — Marketing assets creators use for content (filter by type/category).
- `influto_set_asset_featured` — Curate which assets show as join-page content examples.
- `influto_get_asset_upload_link` — Signed deep-link the HUMAN opens to upload asset files.
- `influto_get_wallet` — READ-ONLY wallet snapshot: balance, reserved, safe_available, can_activate_campaigns, and invite_capacity (marketplace slots + daily email budget) — read before inviting.
- `influto_get_wallet_topup_link` — Signed deep-link to the billing page — the HUMAN completes the Stripe checkout.
- `influto_localize_campaign` — Localize campaign copy (server translator, or hands the copy back for the agent to translate + write back).
- `influto_doctor` — Auth mode, principal, scopes, orgs, per-app freshness — call FIRST when anything misbehaves.

## REST surface (/api/agent/*)

Every MCP tool above proxies one of these endpoints — the REST surface is public and equivalent
(same auth, same scopes, same tenancy). Send `Authorization: Bearer <it_mcp_* key or OAuth token>`.

**Identity & provision**

```
GET  /api/agent/whoami
GET  /api/agent/doctor
POST /api/agent/organizations
GET  /api/agent/store/search · GET /api/agent/store/scrape
GET  /api/agent/apps/check-slug/{slug}
POST /api/agent/provision
POST /api/agent/apps/{app_id}/regenerate-webhook-secret
```

**Configure validation**

```
GET  /api/agent/apps/{app_id}/validation-status
POST /api/agent/apps/{app_id}/credential-setup-link
PATCH /api/agent/apps/{app_id}/apple-meta
POST /api/agent/apps/{app_id}/validate-store-credentials
POST /api/agent/apps/{app_id}/activate-store-direct
```

**Verify (the loop)**

```
GET  /api/agent/apps/{app_id}/integration-status
GET  /api/agent/apps/{app_id}/events/recent
POST /api/agent/apps/{app_id}/test-integration
GET  /api/agent/apps/{app_id}/verify-user-conversions?app_user_id=…
```

**Operate (apps · campaigns · bonuses · analytics)**

```
GET  /api/agent/apps · GET/PATCH /api/agent/apps/{app_id}
GET  /api/agent/campaigns · GET/PATCH /api/agent/campaigns/{campaign_id}
POST /api/agent/apps/{app_id}/campaigns
POST /api/agent/campaigns/{campaign_id}/status
GET  /api/agent/bonus-awards · POST /api/agent/bonus-awards/{award_id}/review
GET  /api/agent/apps/{app_id}/analytics/overview
GET  /api/agent/campaigns/{campaign_id}/funnel
GET  /api/agent/analytics/top-affiliates
GET  /api/agent/campaigns/{campaign_id}/daily-performance
```

**Grow (creators · codes · assets · wallet)**

```
GET  /api/agent/campaigns/{campaign_id}/affiliates
POST /api/agent/campaigns/{campaign_id}/invite
GET  /api/agent/campaigns/{campaign_id}/join-link
GET  /api/agent/invitations
GET/POST /api/agent/apps/{app_id}/free-codes
GET  /api/agent/apps/{app_id}/assets · POST /api/agent/assets/{asset_id}/featured
POST /api/agent/apps/{app_id}/asset-upload-link
GET  /api/agent/wallet · POST /api/agent/wallet/topup-link
POST /api/agent/campaigns/{campaign_id}/localize
```

## The VERIFY loop (why integrations trust InfluTo)

1. The SDK in the developer's build fires real `/sdk/init` + `/sdk/track-install`.
2. `influto_integration_status` (or `GET /api/agent/apps/{app_id}/integration-status`) rolls up
   a 7-step checklist: app_created → campaign_active → sdk_initialized → sdk_event_received →
   validation_configured → purchase_webhook_seen → attributed_conversion.
3. `influto_test_integration` fires a SANDBOX INITIAL_PURCHASE through the REAL pipeline.
4. `influto_recent_events` shows the webhook with `attributed: true` + the referral code.
5. `attributed_conversion_count >= 1` and `live: true` — proof, not vibes. The offline twin is
   the plugin's `scripts/verify_integration.py` (exit 0/1, CI-gateable).

## Troubleshooting

- **Start with `influto_doctor`** — it is deliberately scope-free and reports auth mode
  (oauth | agent_key), principal, granted + hard-denied scopes, organizations, app count and
  per-app SDK-init freshness. A misconfigured connection can still diagnose itself.
- **401 on /api/agent/*** — expired/revoked token or key; reconnect (OAuth) or mint a new key.
- **401 on /api/apps/*** — wrong surface: that is the dashboard-session API. Use /api/agent/*.
- **403** — missing scope (the error names it). **404 on an id you "know" exists** — the id
  belongs to another org; agents only see their granted org.
- **402 on activate/invite** — wallet escrow below minimum; call `influto_get_wallet_topup_link`
  and hand the URL to the human, then retry.
- Campaign not attributing? Codes only attribute while the campaign is **active** —
  `influto_get_join_link` also warns when a link is not shareable yet.

## Install as a plugin (Claude Code)

```
/plugin marketplace add influto/influto-plugin
/plugin install influto
```

Two skills ship with it: `influto-integration` (writes the SDK code, works offline) and
`influto-platform` (drives this control plane). First tool call opens the browser consent —
that's the whole onboarding.

---
Machine docs index: [/llms.txt](/llms.txt) · Full corpus: [/llms-full.txt](/llms-full.txt) ·
Wire contract: [/contract.md](/contract.md)