Building a Platform With a Public Partner API: What It Actually Costs

What changes the day someone else's code calls yours

Internal APIs are cheap because you can fix both ends in one pull request. A partner API removes that. Every change after the first integration is a negotiation with people who will not deploy on your schedule.

Here is the shape it takes. You have a status field with three values. You ship a fourth, paused, in a sprint nobody flagged as risky, because your own frontend has a default case and handles it fine. A partner generated a Java client from your OpenAPI spec eight months ago. Their deserializer throws on an unknown enum value. Their consumer stops processing your webhooks entirely, not just the paused ones, and the backlog grows for six hours until someone notices. The ticket arrives addressed to your CEO, because that is who their VP knows.

Adding an enum value is a breaking change. It is on nobody's list of breaking changes, it passes every test you have, and it is the most common way partner integrations die. That is what a partner API budget actually buys: not endpoints, but the machinery that stops that deploy from shipping.

Versioning is the decision, and there are three real options

• URL versioning (/v1, /v2). Visible, simple, and it forces a big bang migration on everyone at once. Fine if you expect two versions ever and have few enough partners that you can email each one personally.
• Date based versioning pinned per API key. A partner is pinned to whatever version was current the day they created their key and opts into a newer one when they choose. Every change ships as a transformation shim converting new responses back to older shapes, chained oldest to newest. This is the Stripe pattern and the only one we have seen hold up past three years and twenty partners. The cost people find in year two: your codebase permanently carries every shim you have ever written.
• Additive only, no versions. New optional fields and nothing else, forever. Cheapest to run, and it works right up until your domain model is genuinely wrong and you cannot fix it.

Whichever you pick, enforcement has to be mechanical. Put an OpenAPI spec diff in CI with a tool like oasdiff and fail the build on a breaking change, so the enum addition above cannot merge without someone consciously overriding it. If your partners are few and known, consumer driven contracts with Pact are stronger, because they test what partners actually consume rather than what your spec claims. Announce removals with the Deprecation and Sunset headers from RFC 8594, not a blog post, so a partner's monitoring can catch it.

Webhooks are a distributed system you are handing to someone else

Every partner asks for webhooks and nobody quotes them properly. What a real implementation owes:

• Signing that is actually verifiable. HMAC-SHA256 over the timestamp concatenated with the raw request body, verified with a constant time compare. The timestamp goes inside the signed payload and you reject anything older than about five minutes, otherwise you have signed a replay attack. Support two active signing secrets at once, or partners can never rotate without dropping events.
• Retries with jitter and a dead letter queue. Exponential backoff without jitter means every event queued during a partner's outage fires the instant they recover, and your retry storm takes them down a second time. Cap retries, park the rest in a dead letter queue, and give the partner a replay endpoint so recovery is theirs to run rather than a support ticket for you.
• An honest statement about ordering. You cannot guarantee it. Ship a monotonic sequence number or the resource version in the payload and tell partners to treat the webhook as a hint and re-fetch. Partners who assume ordering will build a state machine on your event stream and blame you when it corrupts.
• SSRF protection on the callback URL. A partner hands you a URL and you make an HTTP request to it from inside your network. Block private and link local ranges, resolve the DNS name and validate the resolved address rather than the hostname (or a partner rebinds it after your check), and deliver from an egress with static IPs so partners can allowlist you.

The isolation question decides your architecture: one partner whose endpoint takes 30 seconds per delivery must not stall deliveries to everyone else. That means per partner concurrency and per partner queues, not one global worker pool. Teams discover this when their largest partner's Friday deploy backs up the queue for all forty.

Rate limits protect you from your own partners

The rate limit is not for abuse. It is for the partner who wrote a nightly job that pages through your entire dataset at 2am, because they could not find an incremental endpoint, and your database is now serving them instead of your customers.

Competent looks like this: a token bucket per partner per endpoint class, since writes are expensive and should not share a budget with reads; 429 with Retry-After; and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers so a well behaved client paces itself instead of hammering into your wall. Then remove the reason for the full sync. Give them an updated_since cursor or a bulk export, because if you do not build the incremental path they will build the nightly full scan and you pay for it forever.

Pagination: cursor, not offset. Offset pagination on a table receiving inserts silently skips and duplicates records while the partner pages, and it surfaces as a data loss accusation six months later with no way to prove which side is wrong. Cursor on a stable composite of created timestamp plus id, and keep the cursor opaque so you can change the implementation later.

Keys, OAuth, and the rotation nobody plans

API keys are the right answer for server to server partner access, and they are usually stored wrong. Store a hash, not the key, and show the plaintext exactly once. Prefix it (sk_live_, pk_test_) so it is greppable and so GitHub's secret scanning partner program can notify you when someone commits one. Allow two live keys per partner at once, because rotation without overlap is a scheduled outage.

OAuth 2.0 is a different product, not a bigger API key. You need it only when a partner's application acts on behalf of your individual users, which brings app registration, redirect URI validation, PKCE, scopes, a consent screen, refresh token rotation, and a way for a user to revoke an app. That is where the jump from $50,000 to $150,000 lives. If your partners are companies integrating as themselves, API keys plus scopes are enough and OAuth is a quarter you did not need to spend.

Error shapes matter more than they should. Use RFC 9457 problem details, give every error a stable machine readable code, and never change what a code means. Partners branch on those strings.

Sandbox parity

Partners ask for a sandbox on the first call, and a sandbox that behaves differently from production is worse than none, because it manufactures confidence that fails in front of the partner's own customer.

Real parity means seedable and resettable data, working webhook delivery rather than a stub, and a way to trigger the states that are hard to reach naturally: a failed payment, an expired subscription, a rate limit, a 500. Partners cannot test error handling against a sandbox that only ever returns 200, so they ship without error handling and you both find out during their launch. Budget two to four weeks and do not ship half of it.

What this costs and what drives the number

These bands come from Digital Heroes delivery experience across 2,000+ projects.

$15,000 to $60,000, 4 to 8 weeks. API keys with scopes, a documented REST surface over a data model that is already fit to expose, signed webhooks with retries and a dead letter queue, per partner rate limiting, cursor pagination, an OpenAPI spec with generated docs, and a breaking change gate in CI.

$50,000 to $130,000, 10 to 16 weeks when the API ships with the first release. You are designing a permanent public contract on top of a product that still changes weekly, and part of that cost is calendar: the contract has to freeze before the product wants to.

$150,000 to $350,000, 6 to 12 months when the API is the product. OAuth with app registration and scopes, a self serve developer portal with key management, a sandbox with seeded data and triggerable states, usage metering accurate enough to invoice against, and audit logging that survives a SOC 2 review.

What moves your number inside those bands:

• Whether your data model is publicly presentable. The biggest swing by far. If the API would expose internal concepts, auto increment IDs and columns named after a 2019 migration, phase one is designing a public model and a translation layer. That is where a $20,000 quote becomes $60,000.
• OAuth on behalf of users. Three to six weeks on its own, and it never leaves.
• Usage based billing. Metering you invoice against has to be idempotent and reconcilable, which is a different bar from metering you graph.
• Sandbox. Two to four weeks, plus a second environment you maintain forever.
• How many partners are already signed. Zero means you can still change your mind. Ten means every decision you make this month is permanent.

The recurring cost that surprises people is not infrastructure. It is the permanent engineering tax of maintaining shims and the support load of partners who read your docs differently than you wrote them.

When you should not build this

Do not own the plumbing unless developer experience is your differentiator. Svix or Hookdeck for webhook delivery, signing, retries and the partner facing debug UI. Kong or Zuplo for the gateway, key management and rate limits. WorkOS if partner auth drifts toward enterprise. Each replaces weeks and absorbs edge cases you have not met yet.

Check the direction of the integration before building anything. If partners want you to integrate with their CRM (Customer Relationship Management), HRIS, accounting or ticketing systems, you may not need a partner API at all. A unified API layer like Merge or Nango covers those categories and removes the build. The partner API is the answer when they need to reach into your data, not when you need to reach into theirs.

Own the whole stack when the API is what you sell, when your domain has no vendor equivalent, or when a compliance boundary rules out routing partner traffic through a third party.

How to brief and vet a developer for this

Brief with facts: how many partners are signed and who they are, whether their code calls you or yours calls them, whether their app acts on behalf of your users or as itself, the largest read a partner will realistically make, and whether you have already published anything you cannot take back.

Then ask these.

• "Is adding a value to an enum a breaking change?" Yes, and they should say it before you finish the sentence. Anyone who says no has not had the 3am ticket.
• "How does a partner rotate a signing secret without dropping events?" Two active secrets. If the answer is a maintenance window, they have not run this.
• "Offset or cursor pagination, and why?" Cursor, with a reason that involves inserts.
• "A partner registers a webhook URL of http://169.254.169.254/latest/meta-data/. What happens?" If they do not recognise that address instantly, your cloud credentials are their next deliverable.
• "One partner's endpoint takes 30 seconds. What happens to the other 39?" You want per partner concurrency. "The queue backs up" is at least an honest wrong answer.
• "What mechanically stops a breaking change from merging?" A spec diff or contract tests in CI. "Code review" is not a mechanism.
• "How do you store API keys?" Hashed, shown once, prefixed. If they say encrypted, ask who holds the key.
• "Show me a sandbox you built. How do I trigger a failed payment in it?" If there is no answer, the sandbox was a copy of staging.

Ask for a paid discovery whose deliverable is the OpenAPI spec and a written versioning policy, before anyone writes an endpoint. The spec is the expensive artifact. The code implementing it is comparatively cheap, and no amount of good implementation rescues a wrong spec.