How to build a partner API: a step-by-step guide for SaaS platform teams

A partner API is the surface you expose to a defined set of external companies — resellers, embedded software vendors, systems integrators, marketplaces — so they can act on your platform on behalf of shared customers. It's not your public API, and it's not an internal service. The contract, auth model, rate limits, and lifecycle all differ.

By the end of this guide, you'll have a working blueprint for scoping, building, and rolling out a partner API that can carry real production traffic. Prerequisites: an existing product with some internal APIs, a way to issue credentials, and at least one named launch partner. Time required: 8–12 weeks for a first cut, longer if you're carving capabilities out of a monolith.

Step 1 — Define the partner contract before the endpoints

A partner API fails when it starts as an endpoint list. Start with the contract: who the partners are, what they can do on behalf of a customer, what they can't, and what the commercial relationship looks like. This shapes every technical decision downstream.

Write down four things:

1. Partner tiers. A design partner with a signed agreement gets different scopes than a self-serve integrator. Two or three tiers is usually enough.
2. Actor model. Does the partner act as themselves, as the customer, or as a specific user inside the customer's tenant? Most partner APIs need all three at different points.
3. Data boundary. What partner sees what customer data, and under whose consent.
4. Lifecycle events. Partner onboarding, credential rotation, offboarding, customer churn.

Don't skip this. Every ambiguity here becomes an auth ticket in month six.

Step 2 — Pick the shape: partner API vs public API

These are different products even when they share code. A public API is open to any developer who signs up. A partner API is gated, contractual, and usually exposes capabilities the public API doesn't.
‍

If you already have a public API, resist the urge to just add scopes and call it a partner API. Partners need capabilities customers shouldn't have — provisioning tenants, reading billing, managing users across accounts — and mixing those into a public surface is how you leak sensitive endpoints.

Step 3 — Design the auth model around delegated access

The hard part of a partner API is auth, not endpoints. A partner acts on behalf of a customer, and that customer's users have their own permissions inside the partner's product. You need three layers:

1. Partner identity. The company. Issued during onboarding, tied to the contract.
2. Customer grant. The customer authorises the partner to access their tenant. Scoped, revocable, auditable.
3. User context. When the partner takes an action, whose permissions apply.

OAuth 2.1 with the authorisation code flow handles layers one and two cleanly. Layer three is where teams improvise, and it's where audits fail. Decide up front: does the partner act as a service account inside the tenant, or on behalf of a specific user? For anything touching customer data, act as the user. Service accounts kill the audit trail.

For a full walkthrough, see OAuth for AI agents: a practical setup guide for delegated access — the delegated access pattern is the same whether the caller is a partner service or an agent.

Step 4 — Scope endpoints to partner jobs, not internal services

A common mistake: expose internal microservices one-to-one and call the collection a partner API. Partners don't want your service topology. They want to do jobs.

Map each partner tier to 5–15 concrete jobs. Examples:

• Provision a new customer tenant with a default plan
• List the customer's active users and their roles
• Sync a subset of the customer's data into the partner's product
• Trigger a billing event on the customer's behalf

Each job becomes one endpoint or a small tight cluster. If a partner needs to call four endpoints in sequence to do one job, the API is wrong — either compose it server-side or redesign the job.

This is also where you decide what to expose from the small fraction of product capability your existing APIs cover versus what needs new surface. Be honest with the launch partner about which jobs are day-one and which are next quarter.

Step 5 — Build the rate limiting and quota model per partner

Partner traffic patterns are burstier than public API traffic. A single partner running a nightly sync for 500 shared customers hits your API harder in ten minutes than your entire public API sees in a day.

Implement two layers:

• Per-partner quotas. Requests per minute, per hour, per day. Set at contract time, adjustable.
• Per-customer sub-quotas. Protects one noisy customer from consuming a partner's entire budget.

Return the conventional headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — or the emerging IETF RateLimit and RateLimit-Policy fields from the httpapi working group's draft. Partners will build backoff against these. If you don't send them, partners guess, and their retries make your incident worse.

Deeper treatment in API rate limiting best practices for SaaS in the agent era.

Step 6 — Ship the onboarding flow before the second endpoint

API partner onboarding is where most partner programmes silently die. The contract gets signed, credentials go out by email, and six weeks later the partner still hasn't made a successful call.

Build these in order:

1. A partner portal (even a bare one) where partners create OAuth clients, view credentials, and see request logs.
2. A sandbox environment with seeded test tenants. Not a shared staging environment — real isolated sandboxes per partner.
3. An OpenAPI spec published to the portal, with per-partner scopes visible. Follow OpenAPI specification best practices — the spec is what partners' code generators consume.
4. A working "hello partner" example in one language that runs against the sandbox in under ten minutes.
5. A single named engineer at your company who owns partner integration escalations for the first year.

If you can't demo a partner going from contract-signed to first successful call in a single afternoon, come back to step six before adding more endpoints.

Step 7 — Version and communicate breaking changes on partner terms

Partners have production systems built on your API. A breaking change without coordination costs them money and burns the relationship.

Set the policy explicitly:

• Version in the URL or an Accept header. Pick one and stick with it.
• Minimum 12-month deprecation window for breaking changes. Longer for contractual partners.
• Sunset and Deprecation HTTP headers on every response from a deprecated version.
• A monthly partner changelog, sent by email to the named contact, not just published to a portal.
• Direct outreach for anything that changes semantics without changing the schema — those are the changes that break partners silently.

See API versioning strategy for SaaS platforms in the agent era for the mechanics.

Common pitfalls

The patterns that break partner APIs are consistent across teams:

• Treating the partner API as a config layer on the public API. They diverge fast. Fork them earlier than feels comfortable.
• Service-account auth for convenience. Kills the audit trail, fails the first serious security review, and is hard to migrate off later.
• Rate limits without headers. Partners retry blind and amplify outages.
• No sandbox, or a sandbox that's just staging with the partner's name on it. Partners test in production, and one of them will do it on a customer.
• Silent capability drift. The API keeps working, but the semantics of a field change. This is the most expensive bug class and the hardest to catch. See third party API change management — the same failure mode partners face when consuming your API.
• One-off endpoints for the biggest partner. Feels pragmatic in month three. By month eighteen you have a partner API where every partner sees a different surface.

The partner API you ship in six months is easier to maintain than the one you ship in six weeks. Design the contract, the auth model, and the onboarding path before the endpoint list gets long.