B2B partner API onboarding: from invite to first live call

Enlarge

B2B partner API onboarding is one of those things that looks simple on paper and turns into a multi-week project in practice. A payment processor needs access to your transaction API. A healthcare data partner needs to pull from your FHIR endpoints. A retail supplier needs to push inventory updates. In every case, the actual API integration takes a day. The onboarding process before that — provisioning credentials, sharing documentation, coordinating test environments, validating access — takes weeks.

The root cause is almost always the same: credentials live in one system, documentation lives in another, and the partner's access scope lives in a third. Someone on your platform team has to manually bridge all three every time a new partner comes on board.

This guide walks through exactly how to run B2B partner API onboarding end to end in Zerq — from the first client record to the partner's first successful live call — using the actual configuration fields, portal flow, and audit trail the platform provides.

Why most API gateways make partner onboarding a support burden

Kong, Apigee, AWS API Gateway, and Azure APIM are built around gateway configuration, not partner experience. Credentials are provisioned separately from documentation. Documentation is published separately from the access control model. There is no native concept of a scoped view that shows a specific partner exactly the APIs they can call — and nothing else.

In practice, this means your platform team becomes the integration layer between your gateway and your partners. You provision an API key or OAuth client, write it down somewhere, email it to the partner's developer, and then wait for them to discover that the documentation describes the API slightly differently from how it actually behaves. They file a support ticket. You reproduce the issue. You fix the documentation. You email them again.

There is also no audit trail for the onboarding process itself. You know when the gateway received a call, but you do not know when the partner first signed in to read the documentation, which endpoints they tested before going live, or whether a second developer from the same organization accessed the credentials. For regulated industries, that gap matters — an auditor asking "who had access to the payment API and when did they first use it" deserves a complete answer, not a partial one.

How Zerq handles it

The developer portal in Zerq is not a separate documentation tool. It is a scoped, authenticated interface built on top of the same access control model the gateway enforces at runtime. When a partner signs in, they see only the collections assigned to their client. The auth headers pre-filled in the testing console are the same credentials that will work against the live gateway. Switching profiles in the portal updates both the displayed credentials and the auth context used for every in-browser test call.

The result is that what the partner sees in the portal is exactly what they will get in production. There is no gap to explain.

Phase 1: admin setup

Step 1: Create the client

Go to Clients in the management UI and click New Client. Fill in the required fields:

Click Create. Zerq automatically creates a default access profile for the client with token authentication.

Step 2: Create and attach a rate limit policy

Before enabling portal access, set up a rate limiting policy appropriate for this partner's tier. Policies control two independent limits: a short-term rate limit (bursting) and a long-term quota.

Go to Policies, click New Policy, and configure:

name: "Standard Partner"
description: "Default limits for commercial API partners"

rate_limit_requests: 100
rate_limit_interval: "1m"      # 100 requests per minute

quota_requests: 50000
quota_interval: "30d"          # 50,000 requests per calendar month

Back on the client, click Edit, select this policy from the dropdown, and save. Both limits apply across all of the client's profiles combined.

Step 3: Enable developer portal access

Open the client, click Edit, and toggle Developer Portal access on. This controls whether the partner's email addresses can request a magic link. It is independent of the client's active/inactive status.

Add the partner's developer email addresses to the Authorized emails list. Each email you add can independently request a sign-in link and access the portal under this client's scope. You can add or remove emails at any time without recreating credentials.

Step 4: Review the sandbox profile

The auto-created profile is ready for sandbox use. From the client's profile page, you can:

• Rename it to sandbox for clarity
• Set an IP restriction if you want to lock sandbox access to the partner's office IP range
• Copy the auto-generated token to share it out-of-band if needed (though the portal handles this automatically)

Step 5: Add a production profile

For high-assurance production traffic, add a second profile with a stronger auth type. Click Add Profile on the client, set the name to production, and choose your preferred auth method — oidc for token governance through your IdP, or mtls for certificate-based identity at the TLS layer.

A client with two profiles gives the partner a clean separation: test freely on sandbox, promote to production when the integration is verified.

Phase 2: the partner signs in

Step 6: Send the partner the portal URL

Tell the partner their developer portal URL and the email address you added as authorized. That is the entire handoff from your side.

Step 7: Partner requests a magic link

The partner navigates to the developer portal sign-in page and enters their authorized email. The request hits:

POST /api/v1/developer-portal/request-link
Content-Type: application/json

{
  "email": "[email protected]"
}

The response is always the same regardless of whether the email is registered, to prevent enumeration:

{
  "message": "If your email is registered, you'll receive a sign-in link shortly."
}

The link is single-use and expires after 30 minutes. If it expires before the partner clicks it, they return to the portal and request a new one.

Step 8: Partner validates the link and gets a session

Clicking the link triggers a token validation call (POST /api/v1/developer-portal/validate-token) and creates an authenticated portal session. The partner is redirected to their consumer dashboard.

Phase 3: API discovery and testing

Step 9: Partner sees only their assigned collections

The dashboard shows every collection assigned to this client. Nothing else. If you have 20 API products and this partner is licensed for 3, they see 3. The catalog is not a filtered view of everything — it is built from the client's collection assignment, so it cannot show what the partner is not supposed to see.

Step 10: Partner uses the testing console

Opening a collection shows the endpoint list. Clicking into any endpoint opens the detail page with a Try It section. The testing console pre-fills three headers automatically from the active profile:

X-Client-ID: 66a1b2c3d4e5f6a7b8c9d0e1
X-Profile-ID: 66a1b2c3d4e5f6a7b8c9d0e2
Authorization: Bearer <sandbox-token>

The partner fills in any required path parameters or request body and clicks Send. The response — status code, latency, full headers, pretty-printed body — comes back in the same panel. If the request is rejected with 403, the partner is calling an endpoint outside their collection assignment. If it returns 429, the rate limit policy kicked in.

Step 11: Partner downloads the OpenAPI spec

Every collection has a downloadable OpenAPI specification generated from the published proxy definitions. The partner can choose OpenAPI 3.0 (broadest tool compatibility — Postman, Swagger UI, code generators) or OpenAPI 3.1 (full JSON Schema 2020-12 support). This spec reflects the actual endpoints they can call, not a global catalog that needs to be manually filtered.

Phase 4: first live call

Step 12: Partner switches to the production profile

The profile selector in the portal header lists every active profile under the client. The partner selects production. All three auth headers in the portal update immediately — the X-Profile-ID changes to the production profile's ID, and the Authorization header changes to the production credential.

Step 13: Partner makes the first live call

The partner copies the updated auth headers or uses the export button to generate a curl command with production credentials:

curl https://gateway.yourcompany.com/v1/payments/initiate \
  -X POST \
  -H "X-Client-ID: 66a1b2c3d4e5f6a7b8c9d0e1" \
  -H "X-Profile-ID: 66a1b2c3d4e5f6a7b8c9d0e3" \
  -H "Authorization: Bearer sk_prod_a8c2f1e4b3d7..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, "currency": "USD", "reference": "ORD-2026-001"}'

That call goes through the same auth enforcement sequence as every other request — profile lookup, credential validation, IP check if configured, method check, collection access check, rate limit, then forward to the upstream. The partner does not need to understand that sequence. It either works or it does not, and the error code tells them why.

The audit trail

Zerq's observability layer records every step of the onboarding process, not just the API traffic. The audit log captures administrative actions — when you created the client, when you enabled portal access, when you added the partner's email. The request log captures portal authentication events and all gateway traffic.

A complete audit trail for a partner onboarding looks like this:

// Admin enables portal access for the client
{
  "timestamp": "2026-08-13T09:00:14Z",
  "actor_type": "user",
  "actor_id": "[email protected]",
  "action": "UPDATE",
  "resource_type": "client",
  "resource_id": "66a1b2c3d4e5f6a7b8c9d0e1",
  "url": "/api/v1/clients/66a1b2c3d4e5f6a7b8c9d0e1",
  "ip_address": "10.0.0.5",
  "response_status": 200
}

// Partner requests magic link
{
  "timestamp": "2026-08-13T09:15:02Z",
  "actor_type": "user",
  "actor_id": "[email protected]",
  "action": "request_login_link",
  "resource_type": "developer_portal",
  "url": "/api/v1/developer-portal/request-link",
  "ip_address": "203.0.113.45",
  "response_status": 200
}

// Partner validates link and creates session
{
  "timestamp": "2026-08-13T09:15:28Z",
  "actor_type": "user",
  "actor_id": "[email protected]",
  "action": "validate_token",
  "resource_type": "developer_portal",
  "url": "/api/v1/developer-portal/validate-token",
  "ip_address": "203.0.113.45",
  "response_status": 200
}

Every subsequent API call through the gateway appears in the request logs with client_id, profile_id, path, method, status code, latency, and full request and response bodies. You can filter by client ID to see everything Acme Payments has ever called, or by profile ID to separate sandbox traffic from production traffic.

For compliance teams, the audit role in Zerq gives read-only access to both the audit log and the request logs without the ability to make configuration changes. Separation of duties is enforced at the role level — the person reviewing the onboarding audit trail is not the same person who performed the onboarding.

What this looks like in practice

A mid-sized payment processor manages integrations with e-commerce platforms that need to initiate payment requests through their API. Before Zerq, their onboarding process involved four internal teams: platform engineering to provision credentials, technical documentation to share API specs, security to review partner requests, and support to handle the inevitable integration questions. End-to-end, a new partner went live in three to four weeks.

After migrating to Zerq, the platform engineer creates the client record, assigns the relevant collections, attaches a rate limiting policy, adds the partner's developer emails, and enables portal access. That takes about ten minutes. The partner receives the portal URL and their email is already in the authorized list. They sign in, explore the payment initiation endpoints in the testing console using real sandbox credentials, download the OpenAPI spec, and make their first test call — all in the same session. The engineering team approves the production profile the following morning, and the partner is live within 24 hours of first contact.

The audit trail from sign-in to first call is complete and queryable by the compliance team without any additional tooling.

What you can do that you could not before

A gateway-native developer portal solves the onboarding problem at the architecture level, not the process level. The partner's view of your API catalog is built from the same data that controls their gateway access. Their credentials in the portal are the same credentials the gateway validates on every request. Their test calls in the portal go through the same auth enforcement sequence as production calls.

You get managed access that is genuinely managed — every email authorized to sign in is on record, every sign-in is logged, every API call is traceable to a client, a profile, and a timestamp. And when you need to add a second developer from the same partner organization, you add their email to the authorized list. No new credentials. No new tickets. No support queue.

Zerq is an enterprise API gateway built for regulated industries — one platform for API management, AI agent access, compliance audit, and developer portal, running entirely in your own infrastructure. See how it works or request a demo to walk through your specific requirements.