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 Supported Providers

owlmetry integrations providers

Shows all supported integration providers with their config fields.

List Integrations

owlmetry integrations list --project-id <id>

Lists all configured integrations for a project, showing provider name, enabled status, and creation date.

Add an Integration

RevenueCat

owlmetry integrations add revenuecat \
    --project-id <id> \
    --api-key <revenuecat-secret-key>

The --api-key is a RevenueCat V2 Secret API key (generated in RevenueCat → 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.

A webhook secret is auto-generated. After creation, the output includes a Webhook Setup section with the exact values to paste into RevenueCat's webhook settings (URL, authorization header, environment, events filter). The authorization header contains the un-redacted secret and is only shown once.

Apple Search Ads

Apple Search Ads setup is two-step — Owlmetry generates the EC P-256 keypair server-side, so there's no openssl and no private key file to manage.

# Step 1 — create the integration. Prints a PEM public key.
owlmetry integrations add apple-search-ads --project-id <id>

The output includes a "Public Key (upload to Apple)" block. Copy the PEM, paste it into ads.apple.com → Account Settings → User Management → (your API user, role "API Account Read Only") → API tab. Apple returns clientId, teamId, keyId.

# Step 2 — save the three IDs Apple returned.
owlmetry integrations update apple-search-ads \
    --project-id <id> \
    --client-id <SEARCHADS.xxx> \
    --team-id <SEARCHADS.xxx> \
    --key-id <key-id>

# Step 3 — pick your org. "Account ID" from the ads.apple.com profile menu.
owlmetry integrations update apple-search-ads --project-id <id> --org-id <org-id>

The integration auto-enables as soon as all four IDs are present. See Apple Search Ads integration concepts for the full setup guide.

Update Config

owlmetry integrations update revenuecat \
    --project-id <id> \
    --api-key <new-key>

# Rotate Apple Ads IDs (the keypair itself is server-managed — to rotate it,
# remove the integration and reconnect to generate a new keypair).
owlmetry integrations update apple-search-ads \
    --project-id <id> \
    --client-id <new-client-id>

Updates are merged with the existing config. Only the fields you pass are changed.

Toggle enabled/disabled:

owlmetry integrations update revenuecat --project-id <id> --enable
owlmetry integrations update revenuecat --project-id <id> --disable

For apple-search-ads, --enable / --disable are ignored — the integration's enabled state is derived from whether all four IDs (client_id, team_id, key_id, org_id) are present.

Test Connection (Apple Search Ads only)

owlmetry integrations test apple-search-ads --project-id <id>

Calls Apple's GET /api/v5/acls endpoint with the stored credentials. On success, prints the list of orgs accessible to the credentials with a checkmark next to the one currently configured. Use this to validate credentials after setup or after rotating a key.

Copy from Another Project

owlmetry integrations copy <provider> \
    --from <sourceProjectId> \
    --to <targetProjectId>

Copies a configured integration from one project to another within the same team — one-step, no Apple-side setup needed. For Apple Search Ads the full config (keypair + client/team/key/org IDs) is duplicated verbatim; the CLI output includes a "connection test" section from a live Apple /acls round-trip confirming the clone works. For RevenueCat the API key is copied but a fresh webhook secret is generated on the target (each project has its own webhook URL — paste the returned values into RC if you want events delivered to the copy's project). Credentials are duplicated, not shared: rotating the source later does not update copies. Requires admin role and integrations:write on the target. Fails with 409 if the target already has a non-deleted integration for that provider, 404 if the source has none, and 403 for cross-team copies.

Re-reveal RevenueCat Webhook Setup

owlmetry integrations webhook-setup revenuecat --project-id <id>

Re-prints the webhook setup block (URL, authorization header, environment, events filter) for an existing RevenueCat integration. The webhook secret is shown once at creation time and redacted on every later list/get response, so this command is the recovery path when the original output was lost. The revealed Bearer <secret> is the same one already configured on RevenueCat — revealing does not invalidate any existing webhook deliveries; remove + re-add the integration to actually rotate it. Admin role + integrations:read.

Remove an Integration

owlmetry integrations remove revenuecat --project-id <id>

Soft-deletes the integration. Can be re-created later.

Sync Data

Sync pulls data from the integration provider's API and updates user properties for existing users.

Sync all users

owlmetry integrations sync revenuecat --project-id <id>
owlmetry integrations sync apple-search-ads --project-id <id>

Queues a background sync for every user in the project. RevenueCat sweeps non-anonymous users and is rate-limited to ~180 requests/minute. Apple Search Ads sweeps every user with a stored asa_campaign_id and resolves any missing names.

Sync a single user

owlmetry integrations sync revenuecat --project-id <id> --user <userId>
owlmetry integrations sync apple-search-ads --project-id <id> --user <userId>

Immediately fetches and updates properties for one user.