Integrations

Integrations connect third-party services (RevenueCat, Apple Search Ads) to a project to sync data into user properties. Configured per project, soft-deletable, and copyable across projects within a team.

list-providers

List supported integration providers and their configuration fields.

list-integrations

List configured integrations for a project.

Returns integrations with their config (sensitive fields are redacted).

add-integration

Add an integration to a project. Config fields depend on the provider — use list-providers to see required fields. Requires integrations:write permission.

RevenueCat example:

{
  "project_id": "550e8400-...",
  "provider": "revenuecat",
  "config": {
    "api_key": "rc_api_..."
  }
}

The api_key is a RevenueCat V2 Secret API key (Project Settings → API Keys → + New secret API key). Required permissions — set at the section level (top-right dropdown on each section), not per individual sub-row: Customer information → Read only AND Project configuration → Read only; all other sections → No access.

Apple Search Ads example — pass an empty config. Owlmetry generates the EC P-256 keypair server-side, stores the private half, and returns the public half for you to relay to the user:

{
  "project_id": "550e8400-...",
  "provider": "apple-search-ads",
  "config": {}
}

The response's config.public_key_pem contains the public key (PEM). Walk the user through uploading it at ads.apple.com → Account Settings → User Management → (their API user, role "API Account Read Only") → API tab. Apple returns clientId, teamId, keyId. Save those via update-integration, then call update-integration once more with org_id (the numeric "Account ID" shown in the ads.apple.com profile menu) — the integration auto-enables when all four IDs are present.

Never ask the user for a private key. Owlmetry always strips private_key_pem / public_key_pem from inbound configs on add-integration and update-integration — those are server-managed. To rotate the keypair, remove the integration and re-add.

Use sync-integration with provider: "apple-search-ads" to backfill names for users already attributed before the integration was connected.

A webhook secret is auto-generated. The creation response includes a webhook_setup object with the exact values to paste into RevenueCat's webhook settings (Settings → Webhooks → + New Webhook):

• webhook_url — the full webhook endpoint URL
• authorization_header — the Bearer token (contains the un-redacted webhook secret; shown only once)
• environment — recommended: Both Production and Sandbox
• events_filter — recommended: All apps, All events

update-integration

Update an integration's config or enabled state. For Apple Search Ads, valid config keys are client_id, team_id, key_id, org_id — the integration auto-enables when all four are set, and enabled is ignored (derived from config completeness). Server-managed keys (private_key_pem, public_key_pem, webhook_secret) are always stripped from input. Requires integrations:write permission.

copy-integration

One-step clone of a configured integration to another project in the same team. For Apple Search Ads, the full config (keypair + client/team/key/org IDs) is duplicated verbatim and the response's connection_test field comes from a live Apple /acls call — confirming the clone works end-to-end. Target is enabled immediately, no Apple-side setup required. For RevenueCat, the API key is copied verbatim but a fresh webhook secret is generated on the target (returned in webhook_setup — paste into RC if you want webhooks delivered to the copy). Credentials are duplicated, not shared — rotating the source does not update copies. Requires integrations:write permission and admin role.

Errors: 409 if the target already has a non-deleted integration for that provider, 404 if the source has none, 403 for cross-team copies or callers without admin role.

get-revenuecat-webhook-setup

Re-reveal the webhook setup block (URL + authorization header + environment + events filter) for an existing RevenueCat integration. Use this when the user lost the post-create output or never captured the auth header — list-integrations redacts the webhook secret. The revealed Bearer <secret> is the same one already configured on RevenueCat; revealing does not invalidate any existing webhook deliveries. To actually rotate the secret, call remove-integration then add-integration. Requires integrations:read permission and admin role.

remove-integration

Remove an integration from a project. Requires integrations:write permission.

sync-integration

Trigger a data sync for an integration. Supports revenuecat (subscription data + ASA name backfill for subscribers) and apple-search-ads (ASA name resolution for every attributed user).

Bulk sync (no user_id) queues a background job — use get-job to monitor progress. Single-user sync is synchronous and returns immediately.