Developer Portal & API Sandbox

⬅️ Day 6: Grow Overview

If you're building a B2B SaaS in 2026 with public APIs, customers (developers) need a developer portal — interactive docs, sandbox environment, API keys management, code examples, SDKs, changelog, status. The naive approach: README on GitHub + Stripe-style docs without sandbox = developers struggle. The structured approach: dedicated /developers section with: interactive API explorer (Postman / Stripe-style), sandbox/test mode, language-specific code samples, SDK downloads, webhooks tester, API key + usage dashboard, support links. Stripe + Twilio + Plaid set the bar in 2026; everyone else compares. (See public-api-chat.md for API design; this is the developer-experience layer on top.)

1. Decide what to include

Developer portal scope.

Core pages:

Landing / overview:
- What's possible
- Use cases
- Quick-start path

Quick start (most-important):
- 5-minute "first request"
- Copy-paste curl / language-specific
- Get to "first response" fast

API reference:
- Auto-generated from OpenAPI spec (recommended)
- Per-endpoint docs with examples
- Try it now (interactive)

Authentication:
- API keys: getting them
- OAuth flow (if applicable)
- Token rotation

Webhooks:
- Subscribe / configure
- Payload formats
- Webhook tester / signature verifier

SDKs:
- Per-language (TypeScript / Python / Ruby / Go / etc.)
- Install + import
- Code samples

Examples / tutorials:
- Complete integration walkthroughs
- Use-case-specific
- "Build X in 30 minutes"

Changelog:
- Version history
- Breaking changes
- Migration guides

Status:
- Real-time API status
- Incident history
- See status-page-chat

Help / support:
- Discord / Slack community
- Support email
- Office hours

Account:

API keys:
- Per-environment (test / live)
- Rotation
- Permissions / scopes

Usage / billing:
- Requests this month
- Quotas / limits
- Plan + upgrade

Webhooks:
- Endpoints registered
- Recent deliveries
- Replay failures

Logs:
- Recent API calls
- Request / response inspection
- Errors

Output:
1. Page structure
2. Quick-start design
3. API explorer choice
4. Account section
5. Mobile considerations

The "5-minute first request" benchmark: developer evaluates in first 5 minutes. If they can't curl + get response in that time, they bounce. Make quick-start ruthless.

2. Interactive API explorer

Live-try-it is critical.

Build interactive API explorer.

Options:

Stripe-style:
- Per-endpoint try-it sidebar
- Auto-fills auth from logged-in user
- Real or test environment
- Code generated in 5+ languages

Swagger UI / Redoc:
- OpenAPI-driven
- Try-it built in
- Less polished than Stripe

Mintlify / ReadMe / Bump:
- Modern docs platforms
- Built-in try-it
- See api-documentation-tools

Custom:
- Full control
- More work

Recommended: Mintlify or ReadMe for SMB; custom for serious.

Authentication in explorer:

Logged-in user:
- Pull their test API key
- Pre-fill auth header
- One-click try

Public docs (not logged in):
- Demo key visible (rate-limited)
- "Sign in to use your key"

Code generation:

Languages:
- curl (always)
- TypeScript / JavaScript
- Python
- Ruby (if applicable)
- Go
- Java / C# (enterprise)
- PHP (legacy users)

Auto-generate from OpenAPI:
- Tools generate snippets
- Per-language idiomatic

Live execution:

Real environment vs sandbox:
- Default: sandbox
- Switch to real with explicit toggle
- Show clear environment indicator

Rate-limit:
- Per-user / per-IP
- Don't let docs explorer DoS production

Output:

Response display:
- Status code, headers, body
- Pretty-printed JSON
- Highlight specific fields

Output:
1. Explorer choice
2. Auth integration
3. Code generation
4. Sandbox vs live
5. Rate limiting

The Stripe-style explorer: per-endpoint sidebar with pre-filled examples. Code generated in user's preferred language. Click to execute live. Best-in-class.

3. Sandbox / test environment

Critical for developer trust.

Build sandbox environment.

What it is:

Separate from production:
- Different API keys (test_xxx)
- Test data (not real)
- No real-world side effects
- Real API behavior otherwise

Use cases:

Developer integration:
- Test before production
- Iterate quickly
- No risk

Customer demos:
- Sales engineers use sandbox
- Customer evaluates without risk

Implementation:

Same code path:
- Test mode = flag in code
- Don't fork codebase
- Same logic; different data

Test mode behaviors:

Skip side effects:
- Don't actually charge cards (Stripe)
- Don't send actual emails (test inbox?)
- Don't notify external systems

Or: simulate:
- Fake card responses
- Test webhook deliveries (you control)
- Configurable scenarios (force decline, force success)

Test data:

Pre-populated:
- Sample customers
- Sample orders
- Realistic but not real

Reset:
- "Reset sandbox" button
- Per-account
- Useful for re-testing

Sample data sets:
- "Healthcare scenario"
- "FinTech scenario"
- For demo purposes

Idempotency:

Sandbox should be idempotent:
- Same test data on every reset
- Predictable
- Reproducible bugs

Authentication:

Per-user sandbox:
- Each developer has own
- Isolated

Or: shared org sandbox:
- Team uses same
- Coordinate

API key separation:

Test keys: pk_test_xxx
Live keys: pk_live_xxx
- Different prefixes
- Hard to confuse

Rate limiting:

Generous in sandbox:
- Don't rate-limit developers learning
- Or: relaxed limits

Output:
1. Sandbox architecture
2. Test data strategy
3. Side-effect handling
4. Reset mechanism
5. Key naming convention

The Stripe test-mode pattern: same API; test keys (sk_test_xxx) act on test data; live keys (sk_live_xxx) act on real. Side-effecting operations skip in test mode. Industry standard.

4. SDK strategy

Languages + maintenance.

Build SDK strategy.

Language priority:

Tier 1 (must-have):
- JavaScript / TypeScript
- Python

Tier 2 (high-priority):
- Go
- Ruby
- Java

Tier 3 (consider based on customer mix):
- C# / .NET
- PHP
- Swift / Kotlin (mobile)

Generation:

OpenAPI-driven:
- OpenAPI spec → generate SDK
- Tools: Speakeasy / Fern / Stainless
- Auto-update from spec changes

Hand-written:
- More polished
- Better idiomatic
- Higher maintenance

Recommended: Generated for Tier 2-3; hand-written for Tier 1 (or generated + polish).

SDK requirements:

Idiomatic:
- TypeScript: types first-class
- Python: snake_case + type hints
- Go: idiomatic Go
- Ruby: idiomatic Ruby

Versioning:
- Semantic versioning
- Match API version

Distribution:

Per-language registry:
- npm (Node)
- PyPI (Python)
- RubyGems (Ruby)
- Go modules (Go)
- Maven (Java)
- NuGet (C#)

Documentation:
- Per-SDK README
- Quick-start
- Full reference

Examples:

Per-SDK:
- Quick start
- Common operations
- Use-case-specific
- Tested in CI

Maintenance:

CI:
- Test SDKs against API
- Run examples
- Catch breaking changes

Release cadence:
- After API changes
- Patch / minor / major

Deprecation:
- Notice in SDK
- Migration path
- Timeline

Tools:

Speakeasy:
- Modern SDK generator
- Quality output

Fern:
- Alternative
- TypeScript-focused

Stainless:
- Modern; growing

OpenAPI Generator:
- OSS classic
- Less polished

Output:
1. Language priority
2. Generation vs hand-written
3. Distribution channels
4. CI testing
5. Tool choice

The Speakeasy / Fern / Stainless trend: high-quality SDK generation in 2026. Better than hand-writing 8 SDKs.

5. API key management UX

Customer-facing UI.

API key management.

UI:

Account → Developer → API Keys.

Create:

Form:
- Name (e.g., "Production server")
- Permissions / scopes
- Environment (test / live)
- Expiration (optional)

Show key:

Once after creation:
- Modal with key
- "Copy to clipboard"
- "I've saved it" confirm
- Warning: won't show again

Reveal limited:
- Last 4 chars after creation
- Or: hash; can't recover

Management:

List:
- Name, last used, created, environment
- Sort / filter

Rotation:
- "Rotate" button
- Old key still valid for 30 days (transition)
- New key replaces

Revocation:
- "Revoke" button
- Immediate effect
- Confirmation

Audit:

Per-key activity:
- When used
- From where (IP)
- Recent requests

Permissions:

Scoped keys:
- Read-only vs full access
- Per-resource permissions
- Like AWS IAM

Examples:
- "read_only" for analytics
- "write_invoices" for billing system
- "admin" full

Lifecycle:

Expiration:
- Optional; some require
- Email reminder before expiry

Inactive cleanup:
- Notify if unused 90 days
- Suggest revoke

Limits:

Max per account:
- 10-20 typical
- Prevent sprawl

Tier-based:
- Free: 3 keys
- Pro: 20
- Enterprise: unlimited

Anti-patterns:

Show full key forever:
- Security risk
- Hash + show last 4

No rotation:
- Hard to update
- Forced to revoke + recreate

Single environment key:
- Mix test + production
- Dangerous

Output:
1. Key creation UX
2. Storage (hashed)
3. Management UI
4. Permissions / scopes
5. Audit

The "show once + hash" rule: API keys are credentials. Hash + show last 4 after creation. If lost, regenerate; can't recover.

6. Usage dashboard for customers

Customers see what they're using.

API usage dashboard.

Metrics:

Request volume:
- Total this month
- Trend (daily / hourly)
- Per-endpoint breakdown

Errors:
- Error rate
- 4xx / 5xx breakdown
- Top errors (which endpoint, which error)

Latency:
- p50 / p95 / p99
- Trend

Quota:
- Used / limit
- Per-plan
- Approaching limit warning

Cost (if usage-billed):
- Request count × cost
- Forecast end-of-month

Per-key breakdown:

Which key did what:
- Identify production vs test usage
- Anomaly detection

UI:

Dashboard:
- Summary KPIs at top
- Charts (line / area)
- Per-endpoint table

Time range:
- Last 24h / 7d / 30d / custom

Export:
- CSV download
- For their own analysis

Alerts:

Approaching quota:
- Email at 80%, 90%, 100%
- In-product banner

Errors spike:
- Alert customer
- "Your error rate increased 5x"

Limits:

Show clearly:
- Free: 1K req/mo
- Pro: 100K req/mo
- Enterprise: unlimited

Used vs limit:
- Progress bar
- Remaining count

Anti-patterns:

Hide usage:
- Customer surprised by overage
- Trust damaged

No per-key breakdown:
- Hard to debug
- Less insight

No alerts:
- Customer hits limit; service breaks
- Surprise

Output:
1. Dashboard layout
2. Metrics tracked
3. Per-key breakdown
4. Alerts
5. Export

The "Stripe API requests" dashboard model: clear; per-endpoint; per-key; trend chart. Customers love transparency.

7. Webhook tester + replay

Developers test webhooks during integration.

Webhook tester.

UI:

Webhooks page.

For each registered webhook:
- URL
- Events subscribed
- Recent deliveries (last 50)
- Status (success / failed)

Per-delivery:
- Timestamp
- HTTP status returned by their endpoint
- Response time
- Headers
- Payload (full)

Actions:

Replay:
- Resend the same payload
- For testing fix

Test:
- Send sample payload
- Don't wait for real event
- Try different event types

Failed deliveries:

Highlight:
- Red status
- "View error details"

Auto-retry:
- 3-5 retries with backoff
- Then DLQ

Manual retry:
- "Replay this delivery"
- Useful after fix

Webhook signature:

Show the signature:
- HMAC of payload
- "Verify with this secret"
- Code samples in SDKs

Code samples:

Per-language signature verification:
- Node.js
- Python
- Ruby
- etc.

Sample payloads:

For each event type:
- "What does customer.created look like?"
- Full sample JSON

Test endpoints (developer-side):

Webhook.site / RequestBin:
- External tools developer uses to receive
- We point to them during testing

Or: built-in:
- Generate temporary URL
- Receive test webhooks
- Inspect payload

Anti-patterns:

No replay:
- Failed delivery permanent
- Frustration

No payload inspection:
- Can't debug
- Black box

No signature docs:
- Insecure implementations
- Vulnerability

Output:
1. Webhook UI
2. Replay mechanism
3. Test sending
4. Signature documentation
5. Code samples

The "replay failed deliveries" feature: customer fixed bug; replays last 100 failed webhooks; back in sync. Saves them from custom catch-up scripts.

8. Quick start + tutorials

Get developers to first success fast.

Build quick-start + tutorials.

Quick start (5 min):

Goal: developer makes first successful API call.

Steps:
1. Sign up / log in
2. Get API key (auto-generated for new account)
3. Copy code snippet (curl + their language)
4. Paste; replace YOUR_API_KEY
5. Run; see response

Critical:
- Each step takes < 1 min
- No external setup (CLI install OK if essential)
- Working in < 5 min total

Code snippets:

Default: curl
Tabs: Node / Python / Ruby / Go / etc.
Each generates working code with their key.

Tutorials (deeper):

Per-use-case:
- "Send your first message" (5 min)
- "Build a payment flow" (15 min)
- "Integrate webhooks" (30 min)
- "Build a chatbot" (1 hour)

Format:
- Step-by-step
- Code samples
- Expected results
- Troubleshooting

Length:
- Short: 5-10 min reading
- Medium: 30 min including coding
- Long: 1-2 hours full integration

Live demos:

CodeSandbox / Stackblitz:
- Working code embedded
- Modify + run

Replit:
- Similar; code-friendly

Pros: zero-setup; tinker freely.

Pitfalls:

Tutorials get stale:
- API changes; tutorial breaks
- CI test against real API
- Auto-update or alert

Too long quick-start:
- "First request" should be 5 min, not 30
- Move complex setup elsewhere

Anti-patterns:

10-step quick start:
- Too much; abandon
- Reduce ruthlessly

No copy-paste:
- Developer types; errors
- Make copy easy

Examples not tested:
- Tutorial has bugs
- Frustration

Output:
1. Quick-start design
2. Tutorial library
3. Live demos
4. CI testing
5. Update cadence

The "quick-start that's actually quick" rule: time it with stopwatch. If >5 min for first response, redesign. Stripe / Twilio nail this.

9. Changelog + versioning

API evolves; communicate.

API changelog + versioning.

Versioning strategy:

Header-based (Stripe):
- Stripe-Version: 2026-01-01
- Per-account default; overridable per request
- Customers don't break automatically

URL-based:
- /v1/, /v2/
- Explicit; less common in 2026

Semantic versioning:
- v1.0, v1.1, v2.0
- For SDKs

Changelog:

Per-version notes:

Major:
- Breaking changes
- New features
- Deprecations

Minor:
- New features
- Bug fixes

Patch:
- Bug fixes
- Performance

Format:
- Date + version
- What changed
- Migration if breaking
- Code samples

Distribution:

Dedicated /changelog page:
- Filtered by impact
- Search
- RSS feed

Email:
- Major changes
- Pre-announce
- Active integrators get notice

Slack / Discord:
- Real-time
- Community

In-product:
- Banner / notification
- "We released v2; migrate by [date]"

Deprecation:

Process:
- Announce 6 months before
- Email reminder
- Sunset date in changelog
- API returns deprecation header

Notice headers:
- Deprecation: <date>
- Sunset: <date>
- Link: <docs>

Customer-side:

Version pinning:
- Customer locks to specific version
- Not auto-upgraded

Forced migration:
- Some changes can't be backwards-compat
- Long notice + tooling
- Migration scripts

Anti-patterns:

Silent breaking changes:
- Trust collapses
- Always announce

No deprecation timeline:
- Customer doesn't know when to migrate
- 6+ month notice standard

Forced upgrade with no warning:
- Production breaks
- Customer fury

Output:
1. Versioning strategy
2. Changelog format
3. Distribution channels
4. Deprecation process
5. Customer pinning

The Stripe-Version header pattern: customers don't break automatically. Each account locked to their preferred version. Industry standard for API longevity.

10. Community + support

Developers help themselves.

Build developer community.

Channels:

Discord / Slack community:
- Public; developers help each other
- Staff monitors
- Free / open
- Used by: Vercel, Resend, Anthropic

Stack Overflow tag:
- Q&A
- SEO benefit
- Less control

GitHub Discussions:
- For OSS-friendly products
- Threaded; searchable

Forum / discourse:
- Some products
- More control than Slack

Office hours:

Weekly / monthly:
- Live Q&A with engineers
- Recorded for replay
- High-engagement

Documentation as product:

Editable / suggest improvements:
- "Edit this page" link
- GitHub-backed docs

Feedback per page:
- "Was this helpful?"
- Track + fix bad pages

Support tiers:

Self-serve:
- Docs + community
- Free

Paid support:
- Email
- Priority response

Enterprise:
- Slack channel
- Dedicated SE / CSM
- SLA

Developer advocacy:

DA team:
- Community engagement
- Tutorials / talks
- Conference presence

Hire when:
- $5M+ ARR with API
- Active community
- Brand-building matters

Anti-patterns:

No community:
- Developers stuck alone
- Slow adoption

Community without staff:
- Stale; questions unanswered
- Worse than none

Slow support:
- API down; customer waits 24h
- Lose enterprise

Output:
1. Channel choice
2. Office hours
3. Documentation feedback
4. Support tiering
5. Developer advocacy

The "active Discord with staff" pattern: Vercel, Resend, Anthropic. Developers ask; community + staff answer; archived knowledge base. Better than support tickets.

What Done Looks Like

A v1 developer portal for B2B SaaS API in 2026:

Add later when product is mature:

The mistake to avoid: 15-minute quick start. Developers bounce. 5-minute or bust.

The second mistake: no sandbox. Every change is risky. Sandbox = trust.

The third mistake: SDKs out of date with API. Customers blocked. CI testing essential.