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

• Hosted: https://api.openpartner.dev
• Self-host: https://api.yourdomain.com (whatever you point at the API service)

Authentication

Three authentication modes:

Mode	Use for
Session cookie (op_session)	Browser portal. Set by /auth/magic/verify.
Bearer API key	Server-to-server. Issued per-partner with scoped permissions.
Admin API key	Bootstrap / CI. Set via ADMIN_API_KEY env. Behaves as headless admin.

Bearer keys carry scopes like partners:write, links:write, commissions:read. The federation contract is documented in Architecture → Network.

Conventions

• All timestamps are ISO 8601 strings in UTC.
• Money values are integers in minor units (cents) plus an ISO 4217 currency code.
• IDs are ULIDs prefixed by entity type: ptnr_xxx, clk_xxx, evt_xxx.
• Pagination is cursor-based via ?cursor=...&limit=....
• Errors return { error: 'code', detail?: ... } with appropriate HTTP status.