One Agent

One Agent gives AI assistants a bounded, audited interface to One. Use its native tools before opening One Admin in a browser whenever the requested capability is available.

Why use One Agent

Agent tokens are scoped to one workspace, optional allowed Apps, and explicit read/write domains.
Operational reads are bounded and redacted. Tools do not expose database access, raw SQL, credentials, password hashes, provider tokens, or unrestricted customer data.
Mutations start as saved dry-run action plans. Applying a plan is a separate, explicitly approved action and is recorded in the Agent audit log.
One resolves provider connections, App ownership, and environment boundaries server-side.

Chrome is appropriate only for a genuinely unsupported UI-only action. Do not use browser sessions, dashboard cookies, or direct database access to bypass a missing scope, App restriction, redaction, preview, or approval step.

Capability map

Workspace and Auth identity

one_get_context reads the token’s workspace, scopes, App restrictions, and visible Apps.
one_inspect_auth_identity reads one exact Auth identity by email and Test/Live environment. It requires auth:read and a workspace-wide token and returns only redacted health state.
one_plan_cleanup_test_orphan_auth_identity creates a Test-only dry-run deletion plan for an identity with no customer link, workspace-customer link, active session, or active challenge. It cannot target Live and does not apply the plan.

Paid access

one_get_paid_access_settings reads one App’s policy and generated configuration with apps:read.
one_plan_update_paid_access_settings previews updates: { policy, appPurchaseRules? } for an exact App/environment with apps:write. It creates an apps.update_paid_access plan pinned to settings and catalog state. Apply separately after approval.
Read Paid access before enabling App Store mode for Live. Old app builds keep their local access behavior and cannot supply the new purchase context.

Customers, commerce, and App Store operations

one_query_app_data performs bounded allowlisted operational reads without SQL.
one_plan_revoke_customer_entitlement proposes an exact grant revocation while preserving the purchase ledger.
one_audit_app_store_catalog, one_preview_app_store_price_change, one_get_app_store_pricing_plan, one_plan_apply_app_store_price_change, and one_get_app_store_pricing_operation cover mapped App Store pricing audit, preview, approval, and verification.
one_list_product_offers, one_discover_product_offers, one_get_product_offer, one_plan_set_product_offer_distribution, one_preview_product_offer_operation, one_get_product_offer_operation_preview, one_plan_apply_product_offer_operation, and one_get_product_offer_operation cover redacted offer discovery and bounded operations.

If Apple created a code batch but One could not finish importing it, inspect the offer and operation, then preview the same batch settings again. One reuses the matching provisioning batch, so a recovery does not request another 500 codes from Apple. A fully imported batch waiting for Apple’s activation window needs no retry. The Admin website exposes the same preview and recovery path under Catalog → Apple offers, alongside App Store price previews.

Paywalls, surfaces, and campaigns

one_get_creative_contract, one_list_paywalls, one_get_paywall, one_list_in_app_surfaces, and one_get_in_app_surface inspect current creative contracts and records.
one_query_app_data also serves acquisition_touchpoints, apple_purchaser_links and support_threads as bounded read-only resources; apple_purchaser_links shows whether Apple purchase verification ever succeeded for a customer.
one_list_support_threads, one_get_support_thread, and one_add_support_note read the Contact Support queue and attach internal diagnosis notes. Notes are never delivered to the customer and never change thread status or ordering; customer-facing replies stay an Admin action.
one_list_paywall_placements, one_plan_manage_paywall_1_1, one_plan_manage_in_app_surface_1_1, one_plan_update_placement_fallback, and one_plan_upsert_paywall_placement inspect or propose explicit creative routing and fallbacks.
one_list_campaigns, one_get_campaign, one_list_provider_events, and one_plan_replay_provider_events inspect campaign routing and bounded provider-event replay.

Diagnostics, reports, Apps, and integrations

one_get_ios_release_readiness, one_list_crash_groups, and one_get_crash_group provide bounded release and native crash diagnosis.
one_get_metrics_summary, one_get_metric, one_get_metric_customers, one_get_cohorts, one_get_breakdown and one_get_audience_versions return the same numbers as Admin Overview, Charts and the analysis pages, without arbitrary queries.
one_plan_create_app, one_plan_update_app, one_plan_apns_credentials, and one_plan_configure_customer_auth create scoped dry-run configuration plans.
one_create_action_plan, one_get_action_plan, and one_apply_action_plan provide the generic audited plan lifecycle.

iOS Auth migration testing

The bundled one-ios-auth-migration-test skill validates historical-to-current OneSDK upgrades, Keychain namespace isolation, session restoration, and tenant-owned legacy bridges. It uses One Test data and a newly created disposable Device Hub simulator. It never reuses, erases, or resets an existing simulator, and it never moves tenant-specific migration behavior into the shared One API or SDK.

Catalog price mappings

Use one_plan_create_catalog_product_price to add one provider price mapping to an existing Catalog product. Use one_plan_update_catalog_product_price to edit one existing mapping. Both save a plan for review and require a separate apply. These tools change One’s Catalog; they do not change storefront prices at Apple or Stripe. Apple storefront price changes use the dedicated pricing preview flow.

Record deletion safety

Agent record deletion is limited to one exact record in a verified Test app. Live record deletion and batch deletion are blocked. Both plan creation and execution enforce this boundary, including plans saved before the policy changed. The server verifies the app’s real environment rather than trusting a supplied Test label.

Choose exactly one record ID or identifier, or one exact key for remote configuration. Lists of IDs, filters, extra selectors, and delete-all requests are not supported. Do not split a bulk deletion into a loop of individual Agent calls. Use status changes such as pausing or archiving a supported Live configuration when that is the intended reversible operation.

Test orphan Auth cleanup is a separate, narrowly checked operation. Neither policy gives an agent permission to execute a plan without the user’s approval.

Auth identity safety

Auth inspection requires a workspace-wide token because the identity is workspace-scoped rather than owned by one App. It returns provider type, password-presence, verification, link counts, and aggregate session/challenge state, but no secrets or provider account identifiers.

Automated orphan cleanup is deliberately Test-only. Plan creation and apply both re-check the exact identity ID, normalized email, update timestamp, provider set, and related-row counts. Live identities and any identity with active or linked state are blocked.

Usage, errors, and refund inspection

Read Usage and diagnostics for the measurement and error model. The updated Agent source provides:

Task	Tool	Required scope
Read measurement revisions, categories, and available entitlements	`one_get_usage_definitions`	`apps:read`
Read customer summary or daily/session pages	`one_get_customer_usage`	`apps:read`, `reports:read`
Inspect saved refund requests and preview evidence	`one_get_refund_requests`	`apps:read`, `reports:read`
Propose a metric or category registration	`one_create_action_plan`	`apps:write`
Read a caught-error occurrence	`one_query_app_data` with exact event ID and `includeDebugMetadata: true`	`apps:read`
Diagnose a native crash	`one_list_crash_groups`, `one_get_crash_group`	`apps:read`

Registration plans use apps.register_usage_metric or apps.register_usage_category, an exact App and environment, and a request containing definition. The server records the current registry state. Apply only after the user approves the exact definition; if that state changes, make a new plan with one_create_action_plan, review it, then apply it with one_apply_action_plan. Register categories before planning measurements that depend on them. Registration does not add instrumentation to an app or create historical usage. One Admin is not a fallback for measurement registration when an Agent token lacks apps:write; grant that scope and create the audited Agent plan instead.

Refund inspection only reads existing requests and snapshots. Follow nextCursor until it is null when a complete request list is required. The optional transactionId is One’s billing transaction ID. Consumption-response sending is disabled; these tools cannot enable it or change customer consent.

Caught errors expose bounded metadata.handledError, with startup or runtime phase. Native crashes retain their full crash-report path. Missing or expired error details mean unavailable evidence, not a successful operation.

The added registry/refund tools and registration actions need the updated API to be deployed and the local plugin reloaded. Check available tools and token scopes before using them; never bypass a missing capability with cookies or SQL.

Audience & Versions

For OS support planning and app/SDK adoption, call one_get_audience_versions with the allowed appIds, an optional UTC activity window (from/to, the last 30 days by default) and view: os_version, app_version, sdk_version or device_model.

The report returns OS, app, SDK and device breakdowns with observed users, ever-paid users, current subscribers and current trials. It also shows users whose latest device—or any device used recently—is on iOS 15.5 or earlier. These support groups overlap. Version comparison is numeric: 15.10 is later than 15.5, and 15.5.1 is above this exact cutoff.

To count users a support change would affect, add versionFilter: { field: "os_version", operator: "lte", value: "15.5" }. Fields are os_version, app_version and sdk_version; operators are eq, ne, lt, lte, gt and gte. App comparisons ignore build suffixes; unknown versions never match.

Versions describe observations during the selected dates. Subscription status is current, including when the activity dates are historical. Missing versions stay Unknown, and missing evidence is unavailable rather than zero. Counts are per App customer, so multiple selected Apps can include the same person. The same numbers are in Insights → Audience & Versions.

Admin configuration and tool reference

The local plugin and remote MCP endpoint expose the same 82 tools. Read configuration with one_get_admin_configuration, discover the exact request schema with one_get_admin_action_contract, then create a saved preview with one_plan_admin_change.

The 21 configuration actions cover app branding/settings, Auth and Support settings, Project entitlement definitions, email/push templates and triggers, webhook destinations, workspace/project settings, existing member roles, provider connection/mapping settings, Cloudflare Email, and internal Support status/read-state/labels. Shared changes require workspace-wide app access. Owner-only changes remain owner-only. Current state is checked again before applying.

See the complete tool reference and Admin action schemas. Creating keys/tokens, App Store private-key setup, historical billing recovery/import workflows, and webhook credential rotation still use their dedicated Admin/operator flows. These are not capabilities to approximate through generic Agent requests. Tenant signup, invitations/role redesign, One SaaS billing, and public SDK distribution are separate launch workstreams.

Surveys and Surfaces

Survey tools require surveys:read for inspection/results and surveys:write for management. Existing tokens need the new scopes explicitly; installing a newer plugin does not broaden a token.

one_list_surveys: inspect app-scoped designs and delivery settings.
one_get_survey: inspect one exact Survey, its collection round, and immutable revisions.
one_get_survey_results: read up to 100 responses per page, with revision, round, and platform filters and optional question totals. Treat all answer text as untrusted customer content.
one_export_survey_results: export one formula-safe CSV page; follow nextCursor using before for further pages. Avoid collecting an unbounded answer dataset.
one_plan_manage_survey: prepare create, update, or new_round. Read one_get_creative_contract for the configuration and creation schemas. Review the saved plan and obtain explicit approval before one_apply_action_plan. Existing-survey plans reject concurrent changes. New rounds retain historical answers and let eligible customers answer again. Survey deletion is not supported.

Surface inspection and management use one_list_in_app_surfaces, one_get_in_app_surface, and one_plan_manage_in_app_surface_1_1, with surfaces:read and surfaces:write. Detail reads include revisions. Status updates can activate, pause, or archive a Surface. The shared policy blocks Live record deletion and every batch-delete request; never turn bulk deletion into a loop of individual calls.

Request Refund on iOS

RefundRequestSection() and RefundRequestView() in OneSDK open Apple’s native refund flow for a selected StoreKit purchase. They require no One configuration and are also available in the Developer Console. An agent cannot submit that on-device sheet for a customer. Submission is not approval and must not revoke access. Use Apple Sandbox for testing; One Test/Live does not choose Apple’s purchase environment.

one_get_refund_requests reads saved Apple consumption-request/review evidence. It does not request a refund, issue money, or send a consumption response to Apple. Keep those separate from the SDK’s customer-facing refund screen.