Partner API

B2B2C endpoints for provisioning customer tenants, sharing integrations, and cross-customer intelligence

The Partner API is for platforms that embed Retivo's intelligence engine into their own product. It requires a tenant with tenant_role = "partner" and an API key with the partner permission.

Authentication

Authorization: Bearer rt_live_...

The API key must have the partner permission scope. Standard keys with full access do not include partner permissions — they must be explicitly granted.

Customer Management

List Customers

GET /api/partners/customers

Returns all customer tenants provisioned by the calling partner.

Response:

{
  "customers": [
    {
      "tenant_id": "uuid",
      "name": "Merchant ABC",
      "slug": "merchant-abc",
      "plan_tier": "growth",
      "plan_status": "active",
      "tracked_user_limit": 5000,
      "created_at": "2026-04-26T10:00:00Z"
    }
  ],
  "total": 1
}

Provision Customer

POST /api/partners/customers

Creates a new isolated tenant with an auto-provisioned API key. Active partner integrations are automatically shared.

Field	Type	Required	Description
`name`	string	Yes	Customer display name
`slug`	string	Yes	URL-safe identifier (lowercase, hyphens only)
`plan_tier`	string	No	`starter`, `growth`, `scale`, `custom` (defaults to partner's tier)
`tracked_user_limit`	number	No	MAU limit (default 1000)
`config`	object	No	Customer-specific config overrides

Response (201):

{
  "customer": {
    "tenant_id": "uuid",
    "name": "Merchant ABC",
    "slug": "merchant-abc",
    "plan_tier": "growth",
    "api_key": "rt_live_..."
  },
  "integrations_shared": 2
}

The api_key is returned only once. Use it for all API calls on behalf of this customer (event tracking, decisions, etc.).

Get Customer

GET /api/partners/customers/{customerId}

Returns full details for a specific customer. Only returns customers that belong to the calling partner.

Integration Management

Register Partner Integration

POST /api/partners/integrations

Define your platform's capabilities once. These are automatically shared with all new customers and can be shared with existing ones.

Field	Type	Required	Description
`provider`	string	Yes	Your platform identifier
`display_name`	string	Yes	Name shown to customers
`domain`	string	No	Domain tag (e.g., `loyalty`)
`action_type_templates`	array	No	Action types to auto-register for customers
`event_mappings`	array	No	Event name mappings

Each action_type_template object:

Field	Type	Description
`name`	string	Action type name (e.g., `grant_points`)
`description`	string	Description for the AI engine
`parameters_schema`	object	JSON Schema for parameters
`delivery_webhook`	string	URL where Retivo dispatches actions

List Partner Integrations

GET /api/partners/integrations

POST /api/partners/integrations/{integrationId}/share

Share a partner integration with a specific existing customer. Auto-registers the action types in their tenant.

{
  "customer_tenant_id": "uuid"
}

Response:

{
  "shared": true,
  "action_types_registered": 3
}

Cross-Customer Stats

Get Partner Stats

GET /api/partners/stats

Aggregate view across all customer tenants.

{
  "total_customers": 47,
  "customers": [
    {
      "tenant_id": "uuid",
      "name": "Merchant ABC",
      "plan_tier": "growth",
      "tracked_user_limit": 5000,
      "created_at": "2026-04-26T10:00:00Z"
    }
  ]
}

Tenant Hierarchy

Role	Description	Can access Partner API?
`standalone`	Default tenant — no hierarchy	No
`partner`	Platform that manages customer tenants	Yes
`customer`	Tenant provisioned by a partner	No (uses standard API)

Partners and their customers are fully isolated at the data level — events, users, interventions, and playbooks never cross tenant boundaries. The learning layer aggregates anonymized patterns across tenants for cross-customer intelligence.

Security

Partner keys cannot read/write customer data directly — they provision tenants and manage integrations
Customer API keys are scoped to their own tenant only
A partner cannot access customers of another partner
Integration sharing only works for integrations owned by the calling partner and customers parented to them

Partner API

On this page