Concepts¶
This page explains the key building blocks of the API Portal & MCP Hub and how they relate to each other.
Organization¶
Each portal instance serves exactly one organization—the top-level container for the portal's APIs, MCP servers, applications, subscriptions, and users. The organization is pinned by handle in the [api_portal.organization] table of config.toml, and is seeded automatically on first startup. The portal refuses to start without a handle.
The database schema itself is multi-organization—one shared database can hold several organizations, each served by its own portal instance—but any single instance is bound to its configured organization, and a request scoped to a different organization is rejected.
The handle appears in every portal URL:
In local-auth mode it must match the organization ID the Platform API asserts in the org_handle claim. In IDP mode the token's organization claim is matched against the organization's idpRefId instead. See Organization settings.
View¶
A view is a filtered, branded subset of the organization's APIs and Model Context Protocol (MCP) servers—for example, one view for internal developers and one for external partners. Each view shows only the artifacts carrying its assigned labels. It can also have its own layout, large language model (LLM) instructions, and API workflows.
Each view has its own URL:
See Manage Views.
Label¶
A label is a tag you assign to an API or MCP server to control which views expose it. A view shows only the artifacts carrying at least one of its assigned labels—so an artifact labelled internal appears only in views that include the internal label. Labels differ from an artifact's tags, which are informational and don't affect visibility. See Manage Labels.
Layout¶
A layout is a custom Handlebars template that defines the structure of a view's pages. It's one part of a theme—a partial copy of the portal's default template tree, holding only the styles, layouts, partials, and page templates you want to change. Anything a theme omits is served from the default. See Theming, and Design Mode for building one offline.
Artifact types¶
The portal serves three kinds of artifact: APIs, MCP servers, and API workflows. Which of them a given portal exposes is an operator setting—the enabled_types allowlist in the [api_portal.artifacts] config. A type that isn't enabled gets no navigation entry and no landing-page section, and its routes return 404. See Artifact types.
API¶
An API is an entry in the portal catalog that developers can discover and subscribe to. The portal supports these API types:
| Type | Definition format |
|---|---|
| REST | OpenAPI (Swagger) YAML/JSON |
| GraphQL | GraphQL schema (SDL) |
| SOAP | WSDL/XML |
| WebSocket | AsyncAPI YAML/JSON |
| WebSub | AsyncAPI YAML/JSON |
Each API can have its own landing page content, documentation sections, icon, and banner image. APIs carry labels (which control view visibility) and tags (informational), and can be marked agent-visible so AI agents discover them. See Manage APIs.
MCP server¶
An MCP server is a Model Context Protocol server published in the portal alongside your APIs—the "MCP Hub" half of the portal. Its contract is its definition—the tools, resources, and prompts it exposes—rather than an OpenAPI-style specification. MCP servers are managed and subscribed to the same way APIs are, and every one of them is agent-discoverable. See MCP Servers and, for the admin side, Manage MCP Servers.
API workflow¶
An API workflow is a published, multi-step sequence of API calls defined in Arazzo format. Workflows are authored by admins and published per view for both human developers and AI agents to discover and follow. See Managing API Workflows and API Workflows.
Subscription plan¶
A subscription plan is a named usage tier that controls how much of an API or MCP server a developer can consume. Plans are attached to an artifact during publishing, and developers choose a plan when subscribing.
Plans can define rate limits—a request count (or event count, for async APIs) per time window (minute, hour, day, or month). When organization.auto_create_subscription_plans is on, a default set of plans (Bronze, Silver, Gold, Unlimited, AsyncUnlimited) is created with the organization. See Subscription Plans.
Application¶
An application is a logical container—representing a mobile app, web app, device, or script—that a developer creates in the portal. For OAuth2-secured APIs, an application holds the client ID(s) that link to OAuth applications created directly in a key manager; the portal never generates or stores consumer key/secret pairs.
A developer can have multiple applications, each with independent OAuth2 client IDs. See Manage Applications.
Note
Applications are not required for subscriptions or API key generation. Subscriptions are made directly to an API or MCP server, and API keys are bound to an API or MCP server—not to an application.
Subscription¶
A subscription is a developer's access grant to a specific API or MCP server under a chosen subscription plan. The plan determines the developer's rate limits and quota for that artifact.
Subscriptions are made directly to the artifact—no application is involved. Once subscribed, the developer can invoke it under the terms of the chosen plan. See Manage Subscriptions.
API key¶
An API key is a simple token bound to a specific API or MCP server, used to authenticate requests to artifacts that use API key-based authentication. API keys are generated per artifact—not per application or per subscription.
API keys can be generated, regenerated (rotated), or revoked. Each of those publishes a webhook event, so a handler in front of your API Gateway can enforce the change once it receives the event—see the Webhook Event Catalog. See Manage API Keys.
Note
The portal generates keys through the UI for REST and WebSocket APIs only. Keys for GraphQL and SOAP APIs exist solely through the API Keys Management API, and keys for MCP servers through MCP Server Keys.
OAuth2 credentials¶
For APIs that use OAuth2, developers create an OAuth application directly in a key manager, then link the resulting client ID to an application in the portal. The portal never sees or stores the client secret—it's supplied by the developer each time they generate an access token, and the portal proxies that token request to the key manager. See Consume an API Secured with OAuth2.
Key manager¶
A key manager is an external OAuth2 authorization server configured for the organization. Developers create and own their OAuth applications there; the portal only stores a reference to the client ID and proxies client_credentials token requests to the key manager's token endpoint. You can configure one or more key managers for the organization. See Key Manager Integration.
Webhook subscriber¶
A webhook subscriber is an HTTPS endpoint you register to receive real-time event notifications from the portal. When an application, API key, or subscription changes, the portal fires a signed HTTP POST to every matching subscriber; what the subscriber does with it—for example, propagating the change to an API Gateway—is up to whatever you run behind that endpoint. See Webhook Integration to register one, and the Webhook Event Catalog for the twelve events and their payloads.