API overview

The OpenPartner API is a REST service over HTTPS that returns JSON. It’s the same API used by the SDK, the portal, and the click router — there’s no internal-only surface.

Base URL

The API is served from your OpenPartner instance under /api:

• Hosted, multi-tenant: https://app.openpartner.dev/api/t/<your-slug> — the path includes your tenant slug between /api and the route. Find your slug in any of your portal URLs (/t/<slug>/...).
• Self-host: https://your-host.example.com/api (no tenant slug — single-tenant mode).

Leaving the slug out of the URL on a multi-tenant install returns:

HTTP 400
{ "error": "tenant_slug_missing", "detail": "..." }

Throughout this reference, <base> refers to the appropriate URL above.

Authentication

Four modes:

Mode	Use for
Session cookie (op_session)	Browser portal. Set by /auth/magic/verify.
Bearer admin key	Server-to-server. Set via ADMIN_API_KEY env, or rotated via POST /api-keys. Behaves as headless admin.
Bearer scoped key	Server-to-server with narrow permissions. Mint under Admin → Integrations, or with POST /api-keys/scoped. Recommended for Zapier / ActivePieces / CRM webhook integrations and in-app referral pages — a leak can’t escalate to full admin.
Bearer partner key	Acts as one partner, and reaches only that partner’s own resources (/partners/<its id>/…). Minted with POST /partners/:id/api-keys. Revoking the partner revokes its keys.

Send the key as Authorization: Bearer <key>. Keys are server-side credentials: never ship one to a browser or mobile app.

Scopes

A scoped key can call only the operations its scopes unlock, and it acts on any partner in your account. Calling something it lacks the scope for returns 403 forbidden_scope with the required scope. Operations that no scope unlocks (billing, programs, payout runs, the admin surfaces) answer a scoped key with 403 forbidden.

Scope	Unlocks
events:write	POST /attribution/events, POST /attribution/conversions, POST /attribution/refunds, POST /coupons/redeem
partners:write	POST /partners, PATCH /partners/:id, POST /import/partners-csv, POST /partners/:id/invite, POST /partners/:id/revoke, POST /partners/:id/coupons, DELETE /partners/:id/coupons/:couponId
partners:create	POST /partners with sendInvite: false and no commission terms, and nothing else. See partners:create keys.
partners:read	GET /partners, GET /partners/:id, and a partner’s /dashboard, /timeseries, /events, /customers and /breakdowns. Also GET /brand-resources.
commissions:read	GET /commissions, GET /partners/:id/commissions
links:read	GET /partners/:id/links
links:write	POST /partners/:id/links
payouts:read	GET /partners/:id/payouts
webhooks:write	POST /webhooks, DELETE /webhooks/:id
clicks:write	POST /clicks. Held by the OpenPartner Network’s federation key; not offered under Admin → Integrations.

A key minted under Admin → Integrations starts with events:write, partners:write, partners:read, commissions:read and webhooks:write: what Zapier, ActivePieces and CRM workflows need. Building an in-app referral page instead? Tick the in-app scopes (partners:create, links:read, links:write, payouts:read) and untick partners:write, so your backend can create each user’s partner and show them their link, earnings and payouts without being able to invite or revoke anyone.

Conventions

• Timestamps: ISO 8601 strings in UTC.
• Money: decimal strings (e.g. "12.00") plus an ISO 4217 currency code. Stored as Postgres numeric; comes back through the JSON layer as a string to avoid float precision loss.
• IDs: ULIDs, sometimes prefixed by entity type (e.g. prt_<ulid> for partnerships, evt_<ulid> for events). Partner IDs are bare ULIDs.
• Pagination: cursor-based via ?cursor=...&limit=.... Endpoints that support it return a nextCursor field (null on the last page).
• Errors: { "error": "<code>", "detail"?: "..." } with the appropriate HTTP status. The error field is a stable machine-readable code; detail is human-readable.

Endpoint reference

• Partners — create, list, invite, revoke, portal access
• Events — record conversion events for attribution, and report refunds
• Conversions by click id — record a conversion against a click, by API or postback URL
• Commissions — list + per-partner commissions
• Webhooks — subscribe to outbound events + signature verification