Partner self-service: from invite to first API call

Enlarge

The friction of B2B partner API onboarding follows a predictable script. Someone emails credentials in a PDF. The partner's developer uses the sandbox token against the production URL. A support ticket arrives three days later. A platform engineer stops what they are doing to debug someone else's integration. Then the partner asks for access to another collection, which requires a manual configuration change, another email thread, and another debugging cycle when the new permissions do not propagate immediately. A partner self-service developer portal is meant to eliminate all of this — but most teams either do not have one or have something that only solves part of the problem.

Zerq's developer portal gives B2B partners governed, scoped, self-service access to the APIs they are contracted to call. The portal is built on top of the same client and collection model that controls gateway traffic, so there is no separate permission system to maintain. Partners see only what their client record allows. Auth headers are pre-filled and copyable. They can run live test calls in the browser before writing a single line of integration code. This guide covers the full flow: from a platform admin creating a client record to the partner completing a successful test call in production.

Why existing approaches fall short

The three approaches teams most often reach for each solve a different subset of the problem while creating problems of their own.

Shared credentials (an API key in a 1Password vault or a service account token distributed by email) get the integration working. They do not get the compliance or operational requirements working. When eight partners share three API key tiers, there is no way to produce a per-partner usage report, enforce per-partner rate limits, or revoke one partner's access without affecting the others. When a compliance team asks which requests Acme Corp made in Q1, the answer is that you cannot tell.

Generic documentation portals like Readme or Stoplight solve the spec distribution problem. They do not touch credential management, rate limiting, or per-partner access scoping. A partner can read your docs, but they need credentials distributed out-of-band, and there is no mechanism to scope what they see based on their contractual access. The interactive testing feature in most documentation portals requires the partner to paste their own credentials, which means the credentials had to be sent some other way first.

Gateway vendor portals (Apigee's integrated developer portal, Kong's DevPortal, AWS API Gateway's usage plans) range from functional to rudimentary, but they share a structural limitation for enterprise B2B deployments. Most use a product-tier model where developers self-register and request access to an API product. This works for public API programs. It does not work when every partner relationship is governed by a contract and you need to control exactly which APIs each named partner can call. Apigee's portal lets unknown developers from a partner organization self-register and request production access. That is not a model most compliance-conscious platform teams can accept.

How Zerq handles partner self-service

Zerq's developer portal uses a managed access model: there is no self-registration. A platform admin enables portal access on a named client record and lists the specific email addresses allowed to sign in. A developer at the partner organization can only access the portal if an admin has explicitly authorized their email. This matches the contractual reality of enterprise B2B API relationships.

Here is the complete setup and onboarding flow.

Setting up the partner client

1. Open the management UI and go to Access Control → Clients.
2. Click New Client and fill in the partner's name, a description, and their primary contact email.
3. In the Collections section, assign only the collections this partner is contracted to access. A client can only call endpoints within their assigned collections; this is enforced at the gateway, not just in the portal display.
4. Attach a Policy if the partner agreement includes rate limits or a monthly request quota. Policies are defined separately and reused across clients (e.g., Enterprise Partner: 2,000 req/min, 5M req/month).
5. Toggle Developer Portal access to enabled.
6. Add each authorized email address to the Authorized emails list: integration lead, developers, QA engineer. Each person on the list can sign in independently and will see the same scoped portal view.
7. Click Create. A default profile is created automatically with token authentication. Add additional profiles as needed: for example, a sandbox profile with liberal limits for development and a production profile with mTLS for live traffic.

The resulting client record captures the complete access contract:

{
  "id": "cl_acme_7x2k",
  "name": "Acme Corp",
  "email": "[email protected]",
  "active": true,
  "has_portal_access": true,
  "authorized_emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ],
  "collections": [
    "coll_orders_v2",
    "coll_inventory_read"
  ],
  "policy_id": "pol_enterprise_2k_5m"
}

The has_portal_access flag and authorized_emails list are the two portal-specific fields. Setting has_portal_access to false immediately prevents any new portal sessions from this client without affecting their API credentials or gateway access. Removing an email from authorized_emails immediately prevents that person from requesting a new magic link.

Once the client is saved, send the partner their portal URL and tell them to sign in with their authorized email. No credentials to transmit. No credential instructions to include. The portal handles authentication.

The partner sign-in flow

1. The partner navigates to the developer portal URL and enters their email address on the sign-in page.
2. The portal calls /api/v1/developer-portal/request-link. The API returns a generic success message regardless of whether the email matches an authorized record (this prevents email enumeration).
3. A sign-in email arrives with a single-use link. The token has a 30-minute TTL.
4. The partner clicks the link. The portal calls /api/v1/developer-portal/validate-token, binds the session to the correct client record, and redirects to the API dashboard.

Passwordless sign-in means there is no password for the partner to store, share, or forget. Each sign-in generates a fresh token. The session is bound to the client record, not to an individual user account; all authorized emails for a client see the same scoped portal.

Discovering the API catalog

The dashboard shows every collection the partner has been assigned to, with collection name, description, and published endpoint count. Other collections in the platform are not visible: no redacted entries, no locked tiles. The partner's catalog is their catalog and nothing else appears.

Clicking a collection opens the collection detail page with a list of all published endpoints (method, path, description) and an Auth Headers panel. The auth headers panel pre-populates the three request headers for the currently active profile:

Each header has an individual copy button. When the partner switches profiles, the values update automatically. The partner can copy these headers directly into their HTTP client, Postman collection, or integration code with no separate credential lookup required.

The collection page also offers an OpenAPI spec download in 3.0 or 3.1 format. Partners use this for typed client generation, Postman import, or internal documentation. The spec reflects the endpoint definitions in Zerq exactly, with no separate spec file to maintain or synchronize.

Testing before shipping

Every endpoint detail page includes a testing console. Auth headers are pre-filled from the active profile. The partner fills in required path parameters, query parameters, and request body if applicable, then clicks Send. The console shows the response status code, latency, full response headers, and pretty-printed response body inline.

This is where most integration questions surface before becoming support tickets. A 403 in the testing console usually means the partner is on the sandbox profile and the endpoint requires a different auth type. A missing required parameter returns 400 with a clear body. Rate limit hits return 429 Too Many Requests with the reason. The partner resolves these observations in the browser before any code is written.

For mTLS profiles, browser-based testing is not reliable for the certificate handshake. The auth headers panel provides a pre-populated curl command for mTLS testing:

curl -X GET "https://gateway.example.com/api/orders" \
  --cert client.crt \
  --key client.key \
  -H "X-Client-ID: cl_acme_7x2k" \
  -H "X-Profile-ID: pr_production_9p3r"

Switching between sandbox and production

If the client has multiple profiles, a profile selector dropdown appears in the portal header. Each profile is listed with its name and auth type badge (TOKEN, JWT, OIDC, mTLS, NONE). Switching profiles immediately changes:

• The X-Profile-ID shown in the auth headers panel
• The Authorization header credential
• The auth context used by the testing console for all subsequent requests

The partner tests the integration on the sandbox profile, confirms it works, switches to the production profile, confirms the production credentials authenticate, and copies the production auth headers for their deployment environment. The whole workflow stays in one interface; there is no separate sandbox portal or production portal.

What the access control looks like in practice

Zerq's security model enforces collection scope at the gateway layer, not just at the portal display layer. If the Acme Corp client is assigned to coll_orders_v2 and coll_inventory_read, a request to any endpoint outside those collections returns 403 regardless of whether the request comes through the portal testing console or a production integration. The portal scopes the partner's view to match what the gateway will actually allow.

If the partner overruns the attached policy's rate limit, the gateway returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your request rate limit. Please try again later."
}

No custom error handling is needed. The policy enforces the agreed limits automatically.

Request logs and the audit trail

Every call the partner makes, test or production, appears in Zerq's request logs with full metadata: timestamp, client ID, profile ID, path, status code, latency, client IP, and request and response bodies. Platform admins can filter logs by Client ID to get a per-partner view of all activity in any time window. This is what makes a compliance question like "what did Acme Corp call in Q1?" answerable in seconds rather than requiring a manual log correlation exercise. See Zerq's observability capabilities for the full field reference.

Every admin action that creates or modifies the client record (enabling portal access, updating the authorized emails list, adding or removing a collection) creates a structured entry in the audit log. The audit log records the actor's identity, the action type, the timestamp, the source IP, and the complete before/after payload. Compliance teams with the Auditor role can query this log to answer exactly when and by whom a partner was granted access to a collection.

What this looks like in practice

A credit data company exposes bureau score and employment verification APIs to a network of partner lending institutions. Before Zerq, onboarding a new partner bank took two to three weeks: a legal review, a manual IAM role configuration in AWS API Gateway, credentials emailed to a primary contact, and an inevitable support cycle when the partner's integration team used the sandbox base URL in their production environment.

After deploying Zerq, the platform team configured two collections (coll_bureau_scores_v2 and coll_employment_verify_v1) and a financial-partner policy with the rate limits from their standard partner agreement. For each new partner bank, the setup takes under ten minutes: create a client, assign the two collections, attach the policy, enable portal access, and add three email addresses from the bank's integration team.

The bank's integration team signs in with a magic link, browses the two collections visible to them, runs test calls against the sandbox profile, exports the OpenAPI spec for their typed client generator, and switches to the production profile to confirm the production token authenticates. Their first successful production call happens the same day as the portal invite. The deployment pattern used here (scoped access for regulated financial data partners) is covered in more depth in Zerq's open banking use case documentation.

The platform team monitors partner usage by filtering request logs to each client ID. When a partner bank approaches their monthly quota, they can see it in the request logs before the partner opens a support ticket. When a partner off-boards, disabling the client record takes effect immediately across both the portal and the gateway.

Closing summary

The developer portal in Zerq gives partners everything they need to integrate successfully without ongoing overhead on your platform team. Managed access means there is no self-registration risk. Magic link sign-in means there is no password management. Scoped visibility means partners see only the collections in their contract. Profile switching means sandbox and production are distinct contexts without a separate portal. The built-in testing console resolves integration questions before they become support tickets. And because the portal is built on the same client and collection model as the gateway, disabling access in one place disables it everywhere. The full architecture overview covers how the portal, gateway, and management plane share a single access model.

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.