Skip to main content

API Portal

Configure and manage API Portals.

Introduction​

An API Developer Portal is a centralized hub designed for developers, architects, and other API-focused roles. It serves as a comprehensive catalog where both internal and external API consumers can discover, understand, and use APIs created by API publishers.

The primary purpose of an API Developer Portal is to ensure that developers can effectively consume APIs when building services and applications. It provides a user-friendly interface to browse API documentation, test API endpoints, and manage credentials.

By offering the above resources, the portal removes the burden of credential management from the API creator. This lets developers handle various aspects of the application development lifecycle independently.

Traefik Hub API Management enables API owners to automatically create a developer portal based on the API resources declared in their cluster.

The APIPortal Object​

The APIPortal object is a Kubernetes Custom Resource Definition (CRD) that allows API owners to create an API Developer Portal. It automatically generates a web interface to browse the documentation of all APIs within its scope. This portal provides a unified view of available APIs tailored to the specific needs of different user groups.

API visibility in the APIPortal depends on user groups. An API will be visible only if the connected API consumer belongs to a group with access to that API, as specified by the API Catalog Item objects. This means that users only see APIs assigned to their groups, maintaining controlled and segmented access.

important

The portal enforces namespace boundaries and considers only API Catalog Item resources within the same namespace as the APIPortal.

Once configured, APIPortals are exposed to end users using Ingress or IngressRoute objects. To do this, follow these steps:

  1. Use an Ingress or an IngressRoute to expose the apiportal Service located in the traefik-hub namespace on port 9903.
  2. Link it with APIPortal resource using the annotation hub.traefik.io/api-portal.

The apiportal Service is automatically created during the installation of Traefik Hub and is located in the traefik-hub namespace. Unless cross-namespace references are supported, the APIPortal must be declared in this namespace.

info

Cross-namespace reference support depends of the Ingress object and therefore depends on the Traefik providers:

  • Ingress object, controlled by the Traefik provider kubernetesIngress, supports cross-namespace, this capability can't be turned off.
  • IngressRoute object, controlled by the Traefik provider kubernetesCRD, supports cross-namespace but the capability needs to be enabled.

You can enable cross-namespace support on IngressRoute resources using the following static configuration:

providers:
  kubernetesCRD:
    allowCrossNamespace: true
tip

Using a combination of Ingress objects for APIPortals and IngressRoute for routing offers more flexibility in managing your APIs. You can define your API, API Catalog Item and APIPortal in one namespace, while still referencing the apiportal Service from the traefik-hub namespace. This approach allows you to maintain security by keeping cross-namespace references turned off on IngressRoute.

This method also simplifies the deployment process, ensuring that your APIPortals are accessible without compromising on namespace isolation.

Configuring Portal Authentication​

The content of an API Developer Portal is only visible to authenticated users. For details on onboarding new users, refer to the User and Group Management documentation page.

Authentication Methods​

Portal authentication can be configured in two ways:

  1. Dashboard Configuration: Configure authentication settings through the Traefik Hub online dashboard
  2. APIPortalAuth CRD: Use the APIPortalAuth Custom Resource Definition for declarative configuration. This method is useful for running Traefik Hub API Management in both online and offline mode.

When both methods are configured, the APIPortalAuth CRD takes precedence over dashboard settings.

Using APIPortalAuth CRD​

To use CRD-based authentication, reference an APIPortalAuth resource in your APIPortal specification:

apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: my-portal
  namespace: default
spec:
  title: "My Portal"
  description: "API documentation"
  trustedUrls:
    - "https://portal.example.com"
  auth:
    name: my-portal-auth  # References APIPortalAuth resource in same namespace

The APIPortalAuth resource must be created in the same namespace as the APIPortal. For detailed configuration options and examples, see the APIPortalAuth documentation.

Trusted URLs Configuration​

To ensure secure authentication, configure the list of trusted URLs in your API Developer Portal setup. The trustedUrls property acts as an allowlist, specifying URLs authorized to receive authentication redirects from the portal. This ensures that sensitive authentication data is only sent to approved destinations.

Typically, the values to include are the host configured in your Ingress object with the path prefix under which your portal is exposed. For example:

trustedUrls:
  - https://portal.example.com/prefix

Configuration Example​

Basic APIPortal​

In this example, we will create a new API Developer Portal for a set of APIs deployed in the default namespace. This example uses dashboard-based authentication configuration.

Basic APIPortal configuration
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: my-portal
  namespace: default
spec:
  title: "My Portal" # The title for the Portal
  description: "API documentation" # A short description of the Portal
  trustedUrls:
    - "https://portal.example.com"
  ui:
    logoUrl: https://traefik.io/favicon.png # URL to a picture used as logo

APIPortal with APIPortalAuth​

This example shows how to configure an APIPortal with CRD-based authentication using APIPortalAuth:

APIPortalAuth configuration
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIPortalAuth
metadata:
  name: my-portal-auth
  namespace: default
spec:
  oidc:
    issuerUrl: https://auth.example.com
    secretName: portal-oidc-secret
    scopes:
      - openid
      - profile
      - email
      - groups
    claims:
      groups: groups
      userId: sub
      email: email
      firstname: given_name
      lastname: family_name

Next, the APIPortal can be exposed:

Ingress exposing the APIPortal
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-portal-ingress
  namespace: traefik-hub
  annotations:
    hub.traefik.io/api-portal: my-portal@default # Reference the APIPortal object
spec:
  rules:
    - host: portal.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: apiportal
                port:
                  number: 9903

Configuration Options​

FieldDescriptionRequiredDefault
titleThe title displayed in the portalNo-
descriptionA description of the portalNo-
trustedUrlsList of URLs authorized to receive authentication redirectsYes-
ui.logoUrlURL to a logo image displayed in the portalNo-
auth.nameName of the APIPortalAuth resource to use for authentication (must be in same namespace)No-

Displaying Custom Content in the API Portal​

You can use Markdown in your API spec’s info.description field to display custom content or enriched documentation.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Weather
  description: |
    # Overview

    Welcome to **The Weather API**. This is a custom introduction using Markdown.

    ## Features
    - Feature A
    - Feature B

    ## Contact
    If you have any questions, contact us at [email protected].
  contact:
    name: TraefikLabs
    url: 'https://traefik.io/'
  license:
    name: Apache 2.0
    url: 'https://spdx.org/licenses/Apache-2.0.html'
tags:
  - name: external
    description: routes exposed publicly
  - name: internal
    description: routes reserved for internal usage
paths:
#...

Related Content​

  • Learn how to use the Traefik Hub API Portal in this section.
  • Learn more about APIPortalAuth for CRD-based portal authentication configuration.