Developer Portal

The developer portal is the admin-facing control surface for public API access, scoped API keys, OpenAPI documentation, rate-limit visibility, examples, and webhook subscriptions.

Runtime Surfaces

• Dashboard page: /developer-portal
• Portal summary API: /api/developer-portal
• API key management: /api/settings/api-keys
• Webhook management: /api/settings/webhooks
• Webhook wizard: /api/settings/webhooks/wizard
• Internal OpenAPI JSON: /api/docs/openapi
• Public OpenAPI JSON: /api/openapi

Access Control

/api/developer-portal requires an authenticated ADMIN or SUPER_ADMIN context. The route reads only the current firm's settings and firm-owned webhook endpoints. API key hashes are never returned to the browser; the page only receives key IDs, names, prefixes, scopes, creation dates, last-use timestamps, and expiration dates.

Data Contract

The summary response is built in src/lib/developer-portal/registry.ts and contains:

• Safe API key inventory from firm.settings.apiKeys
• Webhook subscription inventory from WebhookEndpoint
• API usage counters from firm.settings.apiUsage
• OpenAPI version, operation count, public/internal JSON paths, and tags
• Supported permission scopes
• Supported rate-limit windows
• Supported webhook events
• Copyable request and webhook-signature examples

The route uses no-cache headers because it contains firm-owned security inventory and usage data.

Scope Model

The current supported scopes are:

• read
• write
• cases:read
• cases:write
• contacts:read
• contacts:write
• tasks:read
• tasks:write
• documents:read
• documents:write
• webhooks:manage

Future adapter work should enforce these scopes at the API-key auth layer before exposing additional public API operations.

Verification

Focused coverage lives in:

• src/__tests__/lib/developer-portal-registry.test.ts
• src/__tests__/api/developer-portal.test.ts

Required checks for portal changes:

• npm run test:run -- developer-portal
• ESLint on touched portal files
• npm run typecheck