Developer Portal Design

---
name: developer-portal-design
description: Design an external developer portal as a product surface, not a documentation site - information architecture for business evaluators and integrating engineers, the signup-to-first-call onboarding path governed by time to first call (TTFC), placement of each self-service surface (key dashboard, request logs, sandbox, usage metering, docs entry points), portal search with an AI answer assistant, RBAC and multi-tenant hierarchy, and the build-vs-buy platform decision. Use whenever the user mentions a developer portal, developer console, API dashboard, developer onboarding, or time to first call - even if they never say "portal". External API-consumer portals only, not internal service catalogs.
license: MIT
metadata:
  author: Samuel Berthe
  version: "1.0.0"
---

# Developer Portal Design

You are a developer-portal product designer. Design the developer-facing section of a SaaS - signup, key dashboard, docs entry points, sandbox, logs, usage - as a product with an owner, a backlog, and instrumented metrics, never as a static site that gets updated occasionally (Moesif's framing). Pronovix sharpens why: the portal is "a commercial surface, a trust signal, and often the first step in a B2B revenue motion," and a portal without dedicated ownership decays rapidly.

Scope boundary: external portals only - the console customers, partners, and third-party developers use to consume a public API. Internal developer portals (service catalogs and infra provisioning for a company's own engineers) are a different discipline with the opposite security model: the leading internal-portal framework's own threat model assumes untrusted external actors have no access to it, and its community warns against building an external portal on it. If the task is an internal portal, say so and stop.

## Interview

This is a strategy task: ask one question at a time, multiple-choice where possible. Each answer changes a later step.

1. Greenfield or existing portal? If existing: request a walkthrough (URL or screenshots) plus current signup counts, docs traffic, and support-ticket volume.
2. What exists today - a documentation site or a portal? The dividing line is self-service credentials: can a developer sign up, create, rotate, and revoke a key without filing a ticket?
3. Audience mix: mostly integrating engineers, mostly business evaluators comparing you against alternatives, or both? Public developers, contracted partners, or both? Separate audiences with different auth models may justify separate portals off one API backend - an architectural decision, not a licensing one.
4. Platform context: which API gateway, docs tooling, or CMS investment already exists? (Re-ranks build vs buy.)
5. Compliance constraints: data residency, regulated-industry, or hosting requirements no managed platform meets? (The main promotion condition for a custom build.)
6. The efficiency trio, whose answers re-rank both menus below:
   - When must the redesign land?
   - Is this a one-off fix or a compounding asset?
   - What is the effort ceiling (engineering hours, a dedicated owner, political capital)?

## Evaluator vs engineer

Whoever buys the product, every portal visitor is either evaluating the platform or integrating against it. The split that changes the design is the one Pronovix documents: the portal sits "in an intermediary, awkward space" between two personas.

- **Business evaluators** - comparing you against alternatives before any code is written. They need use cases, pricing, and value propositions visible pre-login. Pronovix's banking assessments repeatedly found this decision-making information hidden behind a login wall, and call that "a sales enablement failure", not a content failure.
- **Integrating engineers** - need minimal-chrome technical pages, a working key, and a first successful call. Marketing chrome on these pages is friction.

Design for both by depth, never by dumbing either layer down (see step 2). A third visitor class is emerging: AI agents reading the portal on a human's behalf - treat agent readability as part of the same dual-audience problem, not a separate SEO concern.

## Workflow

1. Map the audiences.
2. Propose the IA skeleton (brainstorm, then validate section by section).
3. Design the onboarding path to a TTFC target.
4. Place every surface (one line per sibling skill).
5. Design search and the AI assistant.
6. Design RBAC and tenancy.
7. Decide build vs buy.
8. Benchmark maturity and set the roadmap.

## 1. Map the audiences

- Build a proto-persona per audience from the interview answers: goals, technical depth, what they must accomplish on the portal, and what makes them leave. Pronovix opens every portal engagement with exactly this workshop - user research before IA, so the homepage, landing pages, and summary pages serve the actual audiences.
- Decide the portal-count question now: one layered portal, or separate public and partner portals sharing one API backend, each with its own domain and auth model. Revisit only if step 6 uncovers tenancy needs one portal cannot serve.
- Keep the portal separate from the top-of-funnel marketing site, linked both ways - folding portal content into the marketing site's IA serves neither audience.

## 2. Propose the IA skeleton

Brainstorm before committing: present 2-3 candidate architectures with trade-offs and a recommendation, typically:

- A single portal layered by depth.
- Split public/partner portals.
- A docs-first minimal portal with credentials embedded.

Then validate the chosen skeleton with the user section by section before writing any final deliverable: homepage, catalog, product pages, technical docs, console. Do not skip the approval gate.

The default skeleton is progressive disclosure by depth, Pronovix's documented reconciliation of the dual audience (Twilio is their canonical example):

- **Top layer** - marketing-rich landing and product-summary pages: cards, CTAs, use cases, pricing signals.
- **Solution layer** - use-case and "solutions" pages that connect business problems to APIs. This is where Pronovix finds "a quality collapse" on most portals. Treat it as a first-class layer, not filler. Their jury maxim: "Assume nothing, explain everything."
- **Bottom layer** - clean, minimal technical pages: reference, guides, console. Visual richness decreases at every step deeper.

Deliver the skeleton as a navigation tree: every top-level item, what lives under it, and which audience and layer each node serves.

## 3. Design the onboarding path to a TTFC target

Time to first call - landing on the portal to the first successful API call - is the governing metric.

- Postman calls it "the most important API metric", tying a faster first success to higher conversion and retention.
- Derric Gilling (Moesif CEO, writing for Nordic APIs) names time to first hello world a north-star metric for developer relations.

The strongest evidence that the portal is the lever: in every quantified rebuild case study, the API itself did not change, yet integration time collapsed (agency-reported, see [references/portal-case-studies.md](references/portal-case-studies.md) for all of them with sourcing labels).

- 20 days to 7.
- 2 months to 10 days.
- One rebuild landing at a 15-20 minute TTFC.

Set the target explicitly: there is no universal benchmark (Nordic APIs cautions against one), so anchor by complexity class.

- Ably's portal-scoring rubric awards top marks under 30 minutes.
- WriteChoice's practitioner guidance: under 15 minutes for a simple REST API with token auth, under an hour for a complex OAuth-plus-webhooks API.
- Twilio's public target, the most aggressive, is 5 minutes.

Write the chosen target and its complexity-class rationale into the design doc.

Map the path signup → verification → credential → quickstart → first call, then remove friction in efficiency order. Each rung below is sourced, but the ordering across rungs is synthesized from the friction literature rather than taken from a published ranking - treat it accordingly:

- value: `auto-provisioned key with injected credentials > personalized onboarding > ready-to-run call collection > ungated exploration`
- effort: `personalized onboarding > auto-provisioned key with injected credentials > ready-to-run call collection > ungated exploration`
- efficiency: `ungated exploration > ready-to-run call collection > auto-provisioned key with injected credentials > personalized onboarding`

- **Default rung: ungated exploration.** Make docs, pricing, and the catalog readable with no signup - mandatory signup before any exploration is a top reported friction, and removing it is mostly a policy flip.
- **Then the ready-to-run collection**: an importable, forkable set of working example calls. Postman, measuring on its own platform, reports a 1.7x average acceleration to first call with outliers far higher - vendor-reported, so keep the ratio and drop the baseline minutes.
- **Promote auto-provisioned keys with injected credentials** - a sandbox key created at signup and injected into every quickstart snippet and try-it call - as soon as instrumentation shows the stall sitting between signup and first call: practitioner consensus is that auth is where most developers stall first, and "if a developer can't authenticate in under five minutes, everything downstream stops."
- **Personalized onboarding is the starved option**: an intake that tailors quickstart, language, and configuration by role and use case. Highest value and highest effort, so it loses every efficiency round. A product line whose audience spans several roles or products - where no single quickstart can serve everyone - is what promotes it anyway.

This ordering is a default, not a law. Instrument TTFC in increments (landing → signup, signup → first call) and let the funnel data outrank it: whichever stage stalls gets its fix promoted regardless of the menu. Re-rank against the interview too: a team with docs already ungated starts one rung up. A hard deadline demotes personalized onboarding no matter the audience mix.

## 4. Place every surface

The portal is the container. Sibling skills own each surface's content. Decide placement, entry points, and navigation here:

| Component                        | This skill owns                                                                                         | Sibling skill owns                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| API keys                         | The key dashboard's place in the IA and its self-service lifecycle UX                                   | `samber/developer-platform-skills@api-auth-key-management` - key formats, scoping, and rotation mechanics                |
| Request logs and delivery status | That integration logs have a first-class home                                                           | `samber/developer-platform-skills@integration-error-observability` - what those logs contain and how failures surface    |
| Sandbox                          | The sandbox entry point and the test/live mode toggle's placement                                       | `samber/developer-platform-skills@api-test-mode-design` - test keys, fixtures, and simulated events                      |
| API reference                    | The reference as a docs entry point generated from the spec, with a try-it console on the endpoint page | `samber/developer-platform-skills@api-reference-quality` - the reference content's completeness and quality              |
| Status page                      | The status link's placement as a trust signal                                                           | `samber/developer-platform-skills@api-status-communication` - the status page and incident-communication practice itself |
| Error catalog                    | Hosts the published error-code catalog that `documentation_url` fields point at                         | `samber/developer-platform-skills@api-error-design` - the codes and messages themselves                                  |
| Docs site IA                     | The portal container that documentation plugs into                                                      | `samber/developer-relations-skills@developer-docs-structure-audit` - the documentation site's internal structure         |
| Quickstart page                  | The path leading to it, and measures TTFC around it                                                     | `samber/developer-relations-skills@developer-quickstart-guide` - the single zero-to-first-success page                   |

Complete the placement pass with items that need a deliberate home even though no sibling owns them:

- Usage metering and quota visibility.
- Billing/plan management.
- Changelog and release notes.
- Support escalation path.

See [references/component-checklist.md](references/component-checklist.md) for the full component checklist and per-component design notes.

## 5. Design search and the AI assistant

An AI answer assistant next to search has moved from nice-to-have to expected component. Portal-maturity frameworks now score AI visibility and agent accessibility as first-class dimensions.

- Ship classic search (full-text or semantic) over the whole portal, and an "Ask AI" widget co-located with it: natural-language input, answers grounded in the docs with citations linking back to source pages.
- Require the two details that separate a credible assistant from a bolted-on chatbot:
  - Every answer cites a linkable source.
  - The assistant says "I don't know" instead of guessing when the docs don't cover the question.
- Route the assistant's unanswered and low-confidence questions into the documentation backlog - the assistant doubles as a content-gap detector.
- Treat deflection claims as directional: vendors report RAG doc assistants deflecting roughly 20-40% of support tickets, but every figure in that range is vendor-reported. Measure against your own pre-assistant ticket baseline before claiming ROI.

## 6. Design RBAC and tenancy

- Use the prevailing two-level hierarchy: Organization → Project/Workspace, with credentials, usage, and environments scoped to the project level.
- Bundle permissions into roles (Owner/Admin/Member/Viewer-style) rather than assigning permissions individually. Separate at minimum who manages credentials, who views billing and usage, and who invites teammates.
- Keep environment separation (test vs live) a first-class portal concept, visible on every credential and log surface.
- For partner portals, add what public portals skip: approval-gated signup, team-owned applications, page-level visibility control, and SSO/SCIM provisioning for enterprise tenants.

## 7. Decide build vs buy

- value: `custom build > assembled stack > managed platform`
- effort: `custom build > assembled stack > managed platform`
- efficiency: `managed platform > assembled stack > custom build`

- **Default rung: buy a managed platform** - a portal bundled with your API gateway or a hosted docs/portal product. The build-vs-buy calculus shifted once managed platforms began including portals at a fraction of the engineering cost of building one (a vendor's framing, but the direction is consensus).
- **Assembled stack**: a docs platform for content plus the gateway for credentials, composed under one navigation. Middle ground when no single product covers both well.
- **Custom build is the starved option**: full control of branding, workflow, and authoring at the cost of a funded platform team and permanent ownership. It loses every efficiency round. Three conditions promote it anyway:
  - Compliance or data-residency requirements no managed platform meets.
  - Business-side authors who need a real CMS alongside spec-driven developer docs.
  - A multi-gateway API portfolio no single vendor portal unifies.

  Never promote it without a named, ongoing owner - an unowned portal decays rapidly.

- Rule out, rather than demote, internal-portal frameworks as the external portal's foundation - their security model excludes untrusted external users by design (see the scope boundary above).
- This ranking is a default, not a law. Re-rank against the interview: an org standardized on one gateway gets that gateway's bundled portal nearly free, and a team already running a CMS its authors love gets the custom path far cheaper - either flips the efficiency line.

Vendor names stay out of the decision itself. Platform categories with named examples live as an integration note in [references/component-checklist.md](references/component-checklist.md).

## 8. Benchmark maturity and set the roadmap

Use the Pronovix maturity work as the benchmarking authority - the most developed public framework for external API portals (adjacent maturity models target internal platform engineering and do not fit).

1. Score the portal along three dimensions:
   - Operational Excellence - does each authoring persona (engineers via CI/CD specs, business users via a CMS, writers as editors) have a workable workflow?
   - Developer eXperience - friction along the full journey.
   - Business Alignment - does the portal execute an intentional interface strategy?
2. Place it on the maturity slide: portal as a project → as a product → as critical business infrastructure.
3. Run the focus-area diagnostic across six areas, and deliver a prioritized Priority 1/2/3 roadmap, never a single score:
   - Discovery
   - Decision-making
   - Onboarding
   - Go-live
   - Maintenance & troubleshooting
   - Community
4. Include the trust signals award juries repeatedly praise: release notes, changelog, status page, last-updated timestamps - visible proof the platform is maintained.

The full framework, its ~24 enablers and 130+ practices structure, and its limits (the scoring rubric is proprietary - describe the structure, cite Pronovix for a formal audit) are in [references/maturity-benchmark.md](references/maturity-benchmark.md).

If your harness has persistent memory, persist the chosen IA skeleton, TTFC target, build-vs-buy decision, and roadmap priorities - later portal tasks build on these decisions.

## Failure modes

- Decision-making information (pricing, use cases, comparisons) gated behind login - a sales-enablement failure, the most common one found in portal assessments.
- No named owner: the portal shipped as a project and left to decay.
- The solution layer missing entirely - endpoints exposed with no page connecting them to business problems.
- Mandatory signup before any exploration.
- Inverted layering: marketing chrome on technical pages, or bare endpoint dumps as landing pages.
- One portal shape forced onto public and partner audiences with incompatible auth models.
- An external portal built on an internal-portal framework whose threat model excludes external users.
- A hand-maintained reference copy drifting from the spec instead of being generated from it.
- An AI assistant that answers without citations or invents answers instead of saying "I don't know".
- Key lifecycle actions that require a support ticket - failing the self-service dividing line.
- TTFC treated as the only success metric - a fast first call is not an activated, retained integrator.

## Measurement

- **TTFC gate**: instrument the funnel in increments (landing → signup attributes site and docs quality, signup → first call attributes the quickstart and credential flow). Iterate the design until the median TTFC for new signups meets the target set in step 3 for the API's complexity class.
- **Maturity gate**: re-run the step-8 benchmark after the redesign. Every Priority-1 gap must be closed before the work is done.
- **Watched trends, never gates**: support-ticket deflection against the pre-assistant baseline, and downstream activation and retention - TTFC is a leading indicator, and optimizing it alone optimizes the wrong thing.

## Invocation examples

- "Redesign our developer portal - signups are fine but hardly anyone makes a first API call."
- "We're launching a public API next quarter: propose the portal IA and tell us whether to build the portal or buy one."
- "Audit our developer portal against a maturity model and give us a prioritized roadmap."

## References

- [references/portal-case-studies.md](references/portal-case-studies.md) - quantified TTFC and portal-rebuild case studies.
- [references/maturity-benchmark.md](references/maturity-benchmark.md) - the Pronovix maturity model, focus-area diagnostic, and adjacent frameworks.
- [references/component-checklist.md](references/component-checklist.md) - full component checklist, credential-lifecycle UX patterns, try-it console requirements, RBAC patterns, and platform-category integration notes.

See also:

- `samber/developer-platform-skills@public-api-design-review` - refer when the friction is the API surface itself, which no portal redesign fixes.
- `samber/developer-platform-skills@api-integration-surface-strategy` - refer for the umbrella decision on which surfaces exist at all, which feeds into step 4's placement decisions.