Letting a partner integrate with your system

Partner API access is a scoped, authenticated doorway your system opens to another company's software. It is not a shared login. In practice you issue credentials per partner, enforce quotas at the gateway, sign webhooks, and keep an audit trail that answers one question fast: which partner made this call, and was it allowed?

Key Takeaways

• Give every partner its own credential. One shared key across three partners means one revocation breaks two innocent integrations.
• Authentication is the easy half. Quotas, idempotency and audit logging are what keep the integration from taking your system down at 2am.
• Set limits before you set expectations: requests per second, burst, daily ceiling and maximum page size.
• Webhooks need the same rigour as inbound calls — signed payloads, retries with backoff, and a delivery queue you can inspect.
• A sandbox with production-shaped quotas prevents the classic "worked in test, melted prod" launch.
• If a partner only needs one daily report, an SFTP drop is cheaper to run and harder to break than an API. Say no when it fits.

What does partner API access actually mean?

Partner API access means exposing a defined set of endpoints to another company's software under its own credentials, separate from your users' logins. It has four parts: an authentication method, usually OAuth 2.0 client credentials or a scoped key; an authorisation model that maps scopes to endpoints; rate limits; and an event channel such as webhooks. Each part is revocable on its own.

Why does partner API access matter more than the integration itself?

Because the credentials outlive the project. An integration that ships in three weeks can sit on your infrastructure for years, calling endpoints nobody remembers writing. When it misbehaves you get the same symptoms as a runaway internal job: saturated database connections, 429 responses for everyone else, and a support queue that starts at nine in the morning.

When do you actually need to open an API to a partner?

You need partner API access when another company's software must read or write your data with no human clicking anything, and the volume or freshness rules out a nightly file drop. You probably don't need it for a single one-way report a day. SFTP with a signed file is cheaper to run and far harder to break.

Ask two questions before you build. Is the data flow real-time enough to matter? And can you name the person on the partner's side who will answer a page? If the answer to the second one is "their account manager", you're about to carry the integration alone.

How does partner API access work under the hood?

The partner authenticates to a token endpoint, receives a short-lived access token carrying scopes, and calls your API with it. Your gateway — NGINX, a dedicated API gateway, or application middleware — validates the token, applies that partner's quota, and writes an audit row. Events travel back over webhooks signed with a shared secret.

How do you set up partner API access step by step?

1. Write the contract down first. Endpoints, field names, error shapes, versioning policy, and an escalation contact. Publish an OpenAPI file so both sides generate clients from one source.
2. Pick the auth model per partner type. Server-to-server jobs get client credentials. A partner acting on behalf of your user gets authorization code with PKCE.
3. Issue credentials from a system you control. One client_id per partner, one secret per environment, stored in a vault — never a spreadsheet or a chat message.
4. Stand up a sandbox with synthetic data and the same quotas as production, so load behaviour shows up before launch.
5. Publish the limits. Requests per second, burst allowance, daily ceiling, maximum page size, and the response headers that report remaining quota.
6. Require idempotency keys on every write. Store the key with the result and replay it rather than processing the same order twice.
7. Run contract tests against the sandbox in CI, on both sides, so a renamed field fails a build instead of a customer's morning.
8. Launch behind a canary. One partner, low quota, alerts on 4xx and 5xx grouped by client_id, then widen.

curl -s -X POST https://api.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=partner-acme \
  -d client_secret="$PARTNER_SECRET" \
  -d scope="orders:read invoices:read"

Rotating that secret is a state-changing operation: it invalidates every in-flight request the partner has open. Keep two secrets valid during an overlap window, confirm the partner has switched, and only then delete the old one. Do it in a quiet hour, not at 4pm on a Friday.

Which configuration actually matters?

Most integration pain comes from defaults nobody chose. Token lifetime decides how often a partner hits your token endpoint. Pagination defaults decide how many rows a careless loop pulls. Idempotency window decides whether a retry is safe. Get these four right and the rest is polish.

• Token lifetime: long enough that partners cache it, short enough that a leaked token expires. Check the current OAuth guidance rather than copying a number from a blog.
• Scope granularity:orders:read beats api:full. Split scopes by resource and by read/write, so a compromised partner loses one capability, not all of them.
• Rate limits and burst: a steady per-second rate plus a burst bucket absorbs the partner's nightly batch without punishing the rest of your traffic. Return Retry-After and expect them to honour it.
• Pagination caps: enforce a maximum page size server-side. A partner asking for 50,000 rows in one call is a database incident waiting for a date.
• Webhook delivery: retries with exponential backoff, a signature header, a delivery log both sides can read, and a dead-letter queue you monitor.

How do you verify a partner integration actually works?

Verification is not a green tick in Postman. It is per-partner metrics you can query during an incident: request volume, error rate and p95 latency grouped by client_id. Add a synthetic call every minute from a canary account, and trace partner requests with a correlation ID so one log search tells the whole story. OpenTelemetry's tracing documentation covers the propagation piece if you haven't standardised headers yet.

What breaks first, and how do you debug it?

In practice the first incident is almost never authentication. It is a partner's retry loop hitting a 500 and hammering you without backoff. The second is a webhook consumer that goes dark on a Saturday. Both show up as capacity problems on your side long before anyone admits the bug is theirs.

• 429 storms: group rejections by client_id. If one partner is retrying immediately, their client ignores Retry-After. Show them the header and ask for exponential backoff with jitter.
• Token endpoint pressure: a partner fetching a token per request instead of caching it. Check token issuance rate against call rate — the ratio should be small.
• Webhook backlog: watch delivery age, not just success codes. A partner whose endpoint takes 30 seconds to respond turns your queue into a growing liability.
• Signature failures: usually clock skew or a body re-serialised before hashing. Compare the raw bytes, and check server time drift.
• Connection exhaustion: a pagination loop with no cursor cap. Look at pg_stat_activity for long-running reads from the same application role.

What does partner API access cost to run?

The bill is less about servers and more about attention. You pay for gateway or application instances that absorb the extra traffic, egress if partners pull large result sets, and log and trace storage that grows with every call. Add engineer time for onboarding, documentation and the support queue, plus the cost of an incident when a partner loops. Confirm infrastructure figures with your provider's own calculator — the drivers, not the numbers, are what you plan around.

Security considerations for third-party API access

Treat every partner as semi-trusted. Give the minimum scope that does the job, keep secrets in a vault, and separate credentials per environment so a sandbox key cannot touch production data. For high-value flows, add mutual TLS or request signing on top of OAuth. Log every call with the client identity, and rehearse the revocation path before you need it — a key you cannot quickly kill is a key you do not control.

Common mistakes we see

The expensive ones are organisational, not technical. A partner integration is a long-term relationship with a piece of software, and it deserves the same access hygiene as a staff account — the same discipline that keeps an access audit honest when people change roles.

• One shared API key across several partners, so nobody can be revoked individually.
• No per-partner rate limit, meaning one integration degrades service for real users.
• Launching without a sandbox, then debugging in production with real customer data.
• Letting the partner's IP allowlist become the only control, and never reviewing it.

A realistic scenario

A Kathmandu logistics company wants order status from your e-commerce platform. Their dispatch system polls every 30 seconds, and they also want a push when an order is cancelled. You issue a client-credentials key scoped to orders:read, cap them at a modest per-second rate with a burst bucket, and give them a signed webhook for cancellations. Two weeks in, their retry logic starts hammering you after a deploy on their side. Because calls are tagged with client_id and logged, you spot it in minutes, throttle that one credential, and everyone else notices nothing. That is the whole point of the design.

Alternatives compared

Direct API plus webhooks is the default, but it is not always the right answer. Batch files and read-only replicas carry real operational weight, and an embedded SSO handoff can remove the integration problem entirely.

Approach	Latency	Operational overhead	Fits when
REST API + webhooks	Seconds	Medium — quotas, auth, audit	Two-way, near-real-time flows
Webhooks only	Seconds, one direction	Low to medium	Partner only needs to react to events
Batch file over SFTP	Hours	Low	Daily reconciliation or reporting
Shared read replica	Near real-time	High — schema coupling	Rarely; usually a mistake
Embedded SSO handoff	Interactive	Medium	Partner works inside your interface, not their own

In short: give each partner its own credential, scope it tightly, cap it before you launch it, log every call against a client identity, and test the revoke path. The integration is the easy part — the access model is what you'll be living with for years.

If you are weighing up whether to open an API at all, or you already have one and it is starting to creak, our team can help you design the access model, review the current setup, and hand over something your own engineers can operate. Custom software development work like this is what we do, and you keep the accounts, the code and the credentials. Tell us what the partner is asking for and we will map the options, or browse past work and our frequently asked questions first.

People also search for

• How to run a website access audit
• Revoking system access when someone leaves
• Onboarding new staff into internal systems
• Custom software versus off-the-shelf tools
• Planning a legacy system replacement
• Business continuity for web systems

Not sure whether your partner needs a full API or a nightly file? Book a review with our team and we will cost the trade-offs before you commit engineering time — or start with our custom software development service to see how we scope integrations.