For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Learn more about common challenges with API portals and how Solo Enterprise for kgateway’s portal fills the gaps.

Portal is a developer portal for Solo Enterprise for kgateway that lets API consumers discover, browse, and interact with APIs. The portal renders an API catalog from OpenAPI specifications and provides self-service features, including team management, app registration, and API key provisioning.

Challenges of API management

Managing APIs across a modern platform introduces challenges that go beyond simple routing and security. Review the most common pain points that organizations face.

• Managing APIs at scale: As the number of microservices grows, manually registering, organizing, and documenting APIs becomes unmanageable. You need a way to onboard APIs without disrupting existing deployment workflows, bundle them into meaningful products for different consumers, and keep documentation automatically in sync without requiring portal admins to intervene for every change.
• Controlling access for the right audiences: Not all APIs should be accessible to everyone. You might need separate portals for internal teams, external partners, or end users, each with different visibility and access rules. Managing who can access which APIs and ensuring they authenticate correctly can quickly become complex when you have multiple audiences and deployment environments.
• Delivering a great developer experience: API consumers need a self-service experience to be productive. Without a branded, easy-to-navigate web UI, interactive documentation, and the ability to generate their own credentials without opening support tickets, adoption of your APIs suffers and your portal admins become a bottleneck.

Developer portal as the solution

A developer portal brings together the tools that API producers and consumers need in one place. Rather than managing API documentation, access control, and credentials across separate systems, a developer portal creates a single, structured layer between your backend services and the teams that consume them.

For API developers, a portal provides a consistent way to register APIs, define products across multiple services, and publish documentation that stays in sync with the underlying services without changing how applications are deployed.

For API consumers, a portal provides a self-service experience to discover APIs, review interactive documentation, request access, and manage credentials. A developer portal can significantly reduce the dependency on admin support and accelerate onboarding.

For platform and security teams, a portal provides centralized access control through subscription workflows, authentication policies, and rate limiting, making it easier to enforce governance across many teams and environments.

Solo Enterprise for kgateway Portal is built on these principles, extending the routing and security capabilities of kgateway with a full developer portal experience.

Key features

Review the following key features to see how Portal addresses common API management challenges.

Key concepts

Review the following key concepts to understand the resources that are used in Portal.

• Portal: A developer portal instance. Creating a Portal CR instructs the controller to deploy a backend web server that serves the API catalog via a REST API.
• ApiProduct: A logical API product with one or more versions. Each version references HTTPRoutes, and the controller automatically discovers and stitches together the OpenAPI schemas for the backends behind those routes.
• ApiDoc: An OpenAPI schema document paired with the backend service it describes. ApiDocs can be authored manually, fetched from a URL, or discovered from an in-cluster service.
• VisibilityPolicy: A policy resource that defines the JWT claim conditions a user must satisfy to see a specific API product in the portal catalog. VisibilityPolicy resources can be attached at the portal level (applies to all API products) or per API product.
• PortalParameters: Operational configuration for a Portal instance, including the data store, web server resources, and identity provider.

Architecture

Review the portal architecture and how the portal resources are connected.

    %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#cce5ff", "primaryBorderColor": "#3399ff", "primaryTextColor": "#003366", "lineColor": "#3399ff", "edgeLabelBackground": "#e8f4ff", "clusterBkg": "#fafafa", "clusterBorder": "#e0e0e0", "secondaryColor": "#e8f4ff", "tertiaryColor": "#ffffff"}}}%%
flowchart LR
    subgraph "User-Created Resources"
        Portal[Portal CR]
        PP[PortalParameters]
        AP[ApiProduct]
        AD[ApiDoc]
        HR[HTTPRoute]
        Svc[Service / Backend]
        VP[VisibilityPolicy]
    end

    subgraph "Controller-Managed"
        PC[PortalConfig]
        SAD[Stitched ApiDoc]
        WS[Portal Web Server]
    end

    FE[Frontend UI]

    Portal -->|parametersRef| PP
    Portal -->|apiProductRefs| AP
    Portal -->|visibilityPolicyRefs| VP
    AP -->|versions.targetRefs| HR
    HR -->|backendRefs| Svc
    AD -->|servedBy| Svc

    AP -.->|controller generates| SAD
    Portal -.->|controller generates| PC
    Portal -.->|controller deploys| WS

    FE -->|REST API| WS
    WS -->|reads| PC
    WS -->|reads| SAD
    WS -->|evaluates| VP
  

Access control model

Portal uses a four-layer model to control who can access the portal, who can see the API catalog, and who can call the APIs.

Layer 1: API visibility in the catalog

Use the visibility field in the Portal custom resource to configure which API products appear in the portal catalog and to whom.

kubectl apply -f- <<EOF
apiVersion: portal.solo.io/v1alpha1
kind: Portal
metadata:
  name: my-portal
  namespace: default
spec:
  parametersRef:
    name: portal-params
  visibility:
    public: true
  apiProductRefs:
  - name: httpbin-api
EOF

kubectl apply -f- <<EOF
apiVersion: portal.solo.io/v1alpha1
kind: Portal
metadata:
  name: my-portal
  namespace: default
spec:
  parametersRef:
    name: portal-params
  visibility:
    visibilityPolicyRefs:
      - name: premium-only
  apiProductRefs:
  - name: httpbin-api
EOF

Layer 2: Portal frontend authentication

Portal frontend authentication is optional for browsing the API catalog and viewing API documentation. However, authentication is required for subscription management and self-service API credentials.

When authentication is enabled and a portal user logs in to the portal frontend by using the Login button, the frontend redirects unauthenticated users to an identity provider via an OIDC authentication flow. The gateway handles the OIDC callback, validates the tokens with the IdP, and stores them server-side in a session. The browser receives only an opaque session cookie. On each subsequent request, the gateway resolves the session and injects the access token as the Authorization: Bearer header before forwarding the request to the portal backend. The portal backend reads the groups claim from that token by default to determine the user’s role, such as whether they have admin privileges. You can change the claim name and the group values that grant admin access by setting spec.adminAuth in your PortalParameters resource.

To enable portal frontend authentication, configure an OIDC identity provider in the PortalParameters resource. For more information, see Secure login.

    %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#cce5ff", "primaryBorderColor": "#3399ff", "primaryTextColor": "#003366", "lineColor": "#3399ff", "edgeLabelBackground": "#e8f4ff", "clusterBkg": "#fafafa", "clusterBorder": "#e0e0e0", "secondaryColor": "#e8f4ff", "tertiaryColor": "#ffffff"}}}%%
sequenceDiagram
    actor User
    participant Frontend as Portal Frontend
    participant IdP as OIDC Provider
    participant Gateway as Gateway (ExtAuth)
    participant Backend as Portal Backend

    User->>Frontend: Visit portal
    Frontend->>User: Redirect to OIDC login
    User->>IdP: Authenticate
    IdP->>Gateway: Authorization code callback
    Gateway->>Gateway: Complete OIDC flow, store tokens server-side
    Gateway->>User: Set session cookie
    User->>Gateway: Subsequent requests with session cookie
    Gateway->>Backend: Inject Authorization: Bearer token
    Backend->>Frontend: Serve catalog and user data based on group claims
  

Layer 3: Subscriptions

When portal users have access to the portal frontend, they can start browsing APIs and review their API documentation. However to access an API, the portal user must belong to a team that owns an app that has an approved API subscription. Subscriptions are requested per app and approved by a portal admin.

Review the following diagram to understand how to set up a team, apps, and API subscriptions. For more information, see Create teams, apps, and subscriptions.

    %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#cce5ff", "primaryBorderColor": "#3399ff", "primaryTextColor": "#003366", "lineColor": "#3399ff", "edgeLabelBackground": "#e8f4ff", "clusterBkg": "#fafafa", "clusterBorder": "#e0e0e0", "secondaryColor": "#e8f4ff", "tertiaryColor": "#ffffff"}}}%%
sequenceDiagram
    actor User
    participant Frontend as Portal Frontend
    participant Backend as Portal Backend
    participant API as API Service
    actor Admin

    Note over User,Backend: Create teams and apps
    User->>Frontend: Create team
    Frontend->>Backend: POST /v1/teams
    User->>Frontend: Register app that consumes <br/> the API
    Frontend->>Backend: POST /v1/apps
    Note over User,Admin: Create and approve subscriptions
    User->>Frontend: Request subscription to ApiProduct <br/> on behalf of an app
    Frontend->>Backend: POST /v1/subscriptions
    Backend->>Admin: Subscription pending approval
    Admin->>Backend: Approve or reject subscription <br/>(requires portal admin privileges)
    Backend-->>Frontend: Subscription status updated
    User->>API: Interact with API (with valid credential)
  

Layer 4: API authentication

After a subscription is approved, requests to the API can be protected so that only credentialed requests are allowed through.

To obtain credentials to access an API, portal admins must first set up credential enforcement for the API. You can choose between API keys and OAuth clients to protect APIs. Then, portal users can self-service credentials via the portal frontend. Credentials are scoped to the ApiProduct the user subscribed to.

Review the following diagram to understand how portal users obtain API credentials and authenticate to access an API. For more information, see Set up API credential management and Create API credentials.

    %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#cce5ff", "primaryBorderColor": "#3399ff", "primaryTextColor": "#003366", "lineColor": "#3399ff", "edgeLabelBackground": "#e8f4ff", "clusterBkg": "#fafafa", "clusterBorder": "#e0e0e0", "secondaryColor": "#e8f4ff", "tertiaryColor": "#ffffff"}}}%%
sequenceDiagram
    actor User
    participant Frontend as Portal Frontend
    participant IdP as OIDC Provider
    participant Backend as Portal Backend
    participant Gateway as Gateway
    participant API as API Service

    Note over User,IdP: Login
    User->>Frontend: Log in to the portal
    Frontend->>IdP: Redirect to OIDC login
    User->>IdP: Authenticate
    IdP->>Gateway: Authorization code callback
    Gateway->>Gateway: Complete OIDC flow, store tokens server-side
    Gateway->>User: Set session cookie
    Note over User,Backend: Credential generation
    alt API key
        User->>Frontend: Generate API key for app
        Frontend->>Backend: POST /v1/apps/{id}/api-keys
        Backend->>Frontend: Return API key (shown once)
    else OAuth client
        User->>Frontend: Register OAuth client for app
        Frontend->>Backend: POST /v1/apps/{appID}/oauth-credentials
        Backend->>Frontend: Return client ID and secret
    end
    Note over User,API: API access
    User->>Gateway: Call API with credential
    Gateway->>Backend: Validate credential and <br/>subscription (portalAuth)
    Backend->>Gateway: Approved
    Gateway->>API: Forward request
    API-->>Gateway: Response
    Gateway-->>User: Return response
  

Next