API Self-Service Subscriptions

Self-service subscriptions let API consumers subscribe their Applications to APIs—or entire API Bundles—directly from the API Portal, without needing approval from the publisher. This contrasts with managed subscriptions, which requires a pre-negotiated contract. Once a plan is attached to a CatalogItem, that API or bundle is automatically exposed for self-service in the Portal, reducing time-to-integration and enhancing developer satisfaction.

Key benefits

• Instant Access: Consumers subscribe and get access immediately without waiting for the publisher to manage their subscription.
• Multiple Plans: Offer different tiers (e.g., Standard, Pro, Unlimited) by defining multiple CatalogItems referencing the same API.
• Low Friction: Publish once, let consumers self-manage their own subscription lifecycle (upgrade, downgrade, unsubscribe).
• Full Control: Publishers still see every subscription in the Hub UI and can suspend or resume as needed.

Self-Service Subscription behavior

Key points:

• Once a plan is present on an API CatalogItem, the API or API Bundle it references is offered as a self-service subscription.
• Consumers can see the API or API bundle in the API Portal and can subscribe immediately, no additional publisher interaction is needed.

Configuring a CatalogItem in the Traefik Hub UI with Self-Service Subscription enabled

hub.traefik.io/catalog-items/new

• Go to the Catalog Items page in the Hub UI
• Create a CatalogItem referencing:
  • Individual APIs, and/or
  • API Bundles containing multiple APIs
• Attach a plan (e.g., Basic, Pro)
• Save your changes to make it visible for self-service subscription on the API portal

Configuring a CatalogItem via the CRD

You don’t have to configure subscriptions solely through the Hub UI. You can also define (or update) an APICatalogItem resource via YAML. Including an API plan in that CatalogItem effectively makes the referenced API (or API Bundle) self-service–enabled in the Portal.

No Plan

apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: weather-managed-only
  namespace: default
spec:
  everyone: true
  apis:
    - name: weather-api

  # No apiPlan => No self-service subscription is offered.
  # This CatalogItem can still be used for managed subscriptions or simply
  # to display the API in the Portal (without a self-service plan).

With Plan

apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: weather-standard
  namespace: default
spec:
  everyone: true
  apis:
    - name: weather-api
  # Specifying an apiPlan toggles self-service subscriptions on for this API (or Bundle).
  apiPlan:
    name: StandardPlan

Self-Service Subscription experience in the API portal

From the API Portal, consumers see either:

• An individual API (which has its own overview page), or
• A Bundle (which does not have an overview page but appears on the left sidebar).

They can subscribe as follows:

1. For a single API: Click the + button on the top-right of the API’s overview page and fill out the subscription form in the pop-up modal.

   For a Bundle: Click the + button on the left sidebar and fill out the subscription form in the pop-up modal. (Bundles have no overview page).

API

portal.traefik

portal.traefik

API Bundle

When a consumer subscribes through a bundle, the result is that individual self-service subscriptions are created for each API in that bundle. The API Bundle simplifies the workflow by showing one subscription step. If the composition of the bundle changes later—adding or removing APIs—the consumer’s existing subscriptions remain only for the APIs that were part of the bundle at the time they subscribed.

portal.traefik

API Bundle Subscription Behavior

If a consumer already has an existing subscription for one or more of those APIs in a bundle, they can choose whether to keep the existing subscription(s) or replace them with a new plan.

2. Confirm the subscription.

For example, after completing the subscription form for an API, you’ll see a confirmation screen like this:

portal.traefik

3. Navigating to the API overview page in the portal will show all your subscriptions (active or suspended)

portal.traefik

Coexistence with Managed Subscriptions

An application might already have a Managed Subscription to the same API(s) or API Bundle. If so:

• A new self-service subscription overrides the managed one (for that API).
• If the consumer unsubscribes from the self-service subscription in the API Portal, the managed subscription is reactivated automatically.
• If the publisher suspends the self-service subscription in the Hub UI, the managed subscription does not become active again; it remains overshadowed until the self-service subscription is actually unsubscribed. The self-service subscription always overrides the managed one, even in the suspended state.
• The publisher can see both self-service and managed subscriptions in the Hub UI, although only the self-service one is “in effect” when both exist.

API Publisher controls

hub.traefik.io/subscriptions/self-service/self-service-subscription-1/

In the Hub UI, the API publisher can:

• View all self-service subscriptions.
• Suspend or resume subscriptions to handle abuse or policy changes.

info

At the time of writing, subscriptions are auto-approved. An optional manual approval workflow will be introduced soon.

Related content

• Learn more about the API object in its dedicated section.
• Learn more about the APIPlan resource in its dedicated section.
• Learn more about the API Portal in its dedicated section.
• Learn more about APICatalogItem resource in its dedicated section.
• Learn more about Managed Subscriptions in its dedicated section.