Skip to main content

API Managed Subscriptions

Manage access to your APIs.

Managed Subscriptions in Traefik Hub allow API managers to grant access to APIs for specific applications based on pre-negotiated agreements with API consumers. This mechanism provides fine-grained control over which applications can consume which APIs, under what plans, and with what consumption policies (e.g., rate limits, quotas).

Managed Subscription behavior​

Key concepts​

  • Application: Represents a consuming entity (e.g., a mobile app, web app) that requires access to APIs. Each application has a unique App ID (appId) used for identification and authorization.
  • API: A service exposed via Traefik Hub that applications can consume.
  • API Plan: Defines consumption policies such as rate limits and quotas for APIs.
  • Managed Subscription: A resource that links applications to APIs under specific plans, granting them the rights to consume the APIs according to the agreed terms.

Why Managed Subscriptions?​

  • Pre-Negotiated Access: Grant API access based on contracts or agreements made.
  • Application-Level Control: Manage API consumption at the application level rather than the user level.
  • Flexible Policies: Apply different API plans to different applications or APIs as needed.
  • Secure Consumption: Ensure that only authorized applications can consume your APIs, enhancing security.

How Managed Subscriptions work​

ManagedSubscription defines the unit of quota and rate limit enforcement in Traefik Hub. This means that all applications, APIs, and API Bundles included in a single ManagedSubscription share the same bucket of quotas and rate limits defined by the associated APIPlan.

tip

If you want each application or API to have its own separate quotas and rate limits, you need to create individual ManagedSubscription resources per application and per API.

Managed Subscription Workflow​

API Publisher Actions​
  • Define APIs and API Plans: The API Publisher creates and defines APIs within Traefik Hub and sets up API Plans that specify rate limits, quotas, and other consumption policies.
  • Create APICatalogItems: Determines which APIs are visible to which user groups on the Developer Portal.
  • Create ManagedSubscriptions: Grants consumption access to specific applications under particular API Plans.
Application management with ManagedSubscription​

Depending on your authentication setup and requirements, applications may or may not need to be created by API consumers via the Developer Portal.

Scenario 1: External Identity Provider (IdP) with JWTs​
  • API Publisher Actions:
    • Shares the appId (client ID) and client secret with the consumer.
    • Creates a ManagedSubscription including the appId to grant access.
  • API Consumer Actions:
    • Uses the provided appId and client secret to generate JWTs.
    • Can start consuming the API immediately without creating an application on the Developer Portal.
note
  • The Gateway checks the appId in the JWT to grant access.
  • The consumer doesn't need to log into the Developer Portal unless they want additional insights (e.g., consumption metrics).
Scenario 2: Using signing key for JWT generation​
  • API Publisher Actions:
    • Sets up JWT auth with a signing key and shares it with the consumer.
    • Requires the consumer to create an application via the Developer Portal to obtain the appId then share it with the Publisher.
    • Creates a ManagedSubscription including the appId generated by the consumer.
  • Consumer Actions:
    • Logs into the Developer Portal and creates an application to obtain the appId.
    • Uses the shared signing key to generate JWTs.
note

The consumer must create the application on the Developer Portal to generate the appId as no external identity provider is involved with the process.

Creating a Managed Subscription​

Managed Subscriptions are defined using the ManagedSubscription Custom Resource Definition (CRD). Below is an example of how to create one.

Example: Granting access to mobile applications​

Scenario: You have two mobile applications (android-app and ios-app) that need access to the weather-api and forecast-api. The weather-api should be accessed under the standard-plan, and the forecast-api under the vip-plan.

Step 1: Define the APIs​

apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: weather-api
  namespace: your-namespace
spec: {}   # Additional specifications for the weather API

Step 2: Define the API Plans​

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: standard-plan
  namespace: your-namespace
spec:
  title: "Standard Plan"
  description: "Standard rate limits and quotas"
  rateLimit:
    limit: 10
    period: 1s
  quota:
    limit: 1000
    period: 720h # Approximately 30 days

Step 3: Create Applications​

Applications are created via the Developer Portal.

  • Android App: appId is android-app
  • iOS App: appId is ios-app

Step 4: Define the Managed Subscriptions​

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
  name: weather-subscription
  namespace: your-namespace
spec:
  applications:
    - appId: "android-app"
    - appId: "ios-app"
  apis:
    - name: weather-api
  apiPlan:
    name: standard-plan
  weight: 100
Configuration Options​
FieldDescriptionRequired
applicationsA list of applications (by appId) that the subscription applies to.Yes
apisA list of APIs that the applications can access.Yes
apiPlanThe API plan that defines the consumption policies for the APIs.Yes
weight (optional)Determines the priority when multiple subscriptions overlap (higher weight takes precedence).No

Outcome​

  • Both android-app and ios-app can access weather-api under the standard-plan.
  • Both applications can access forecast-api under the vip-plan.
  • The quota & limits defined by the vip-plan will be shared between the 2 applications.

Using API Bundles​

Optionally, if you have multiple APIs that you want to manage collectively, you can define an APIBundle.

apiVersion: hub.traefik.io/v1alpha1
kind: APIBundle
metadata:
  name: weather-bundle
  namespace: your-namespace
spec:
  apis:
    - name: weather-api
    - name: forecast-api

Outcome​

  • Both applications can access all APIs within the weather-bundle under the vip-plan.
  • All APIs of the weather-bundle will share the same quota & limit defined in the vip-plan

Using Claims​

The claims field in the ManagedSubscription resource allows you to define expressions that validate claims in incoming requests to authorize access. This feature provides fine-grained control over who can consume your APIs based on the claims present in a JWT authentication token.

The claims field accepts a string containing a logical expression. This expression can reference claim keys and use logical operators to define complex authorization rules. Only requests with claims that satisfy the specified expression are authorized under the ManagedSubscription.

info

To use claims, JWT authentication is required.

Use Cases​

  • Role-Based Access Control: Allow only users with specific roles to access certain APIs.
  • Group Membership Validation: Restrict access based on group memberships defined in the token.
  • Custom Claim Enforcement: Use custom claims to implement organization-specific authorization logic.
info

The claims field is optional. If not specified, the ManagedSubscription authorizes requests based on only the application and apis fields.

Available Functions and Operators for Claims Expressions​

Function / OperatorSyntaxDescriptionExample
EqualsEquals(claimName, expectedValue)Checks if the claim claimName equals expectedValue."Equals(`grp`, `admin`)"
NotEqualsNotEquals(claimName, unexpectedValue)Checks if the claim claimName does not equal unexpectedValue."NotEquals(`status`, `inactive`)"
ContainsContains(claimName, value)Checks if the claim claimName (string or array) contains value."Contains(`roles`, `manager`)"
PrefixPrefix(claimName, prefix)Checks if the claim claimName starts with prefix."Prefix(`email`, `admin@`)"
OneOfOneOf(claimName, value1, value2, ...)Checks if the claim claimName equals any of the provided values (value1, value2, etc.)."OneOf(`department`, `sales`, `marketing`)"
SplitContainsSplitContains(claimName, separator, value)Splits the claim claimName using separator and checks if any resulting element equals value."SplitContains(`scopes`, ` `, `read`)"
AND Operatorexpression1 && expression2Logical AND of two expressions; evaluates to true if both expressions are true."Equals(`grp`, `admin`) && Contains(`roles`, `manager`)"
OR Operatorexpression1 || expression2Logical OR of two expressions; evaluates to true if either expression is true."Equals(`grp`, `admin`) || Equals(`grp`, `superuser`)"
NOT Operator!expressionLogical NOT of an expression; evaluates to true if the expression is false."!Equals(`status`, `inactive`)"
Parentheses(expression)Groups expressions to control evaluation order."(Equals(`grp`, `admin`) || Equals(`grp`, `superuser`)) && Contains(`roles`, `manager`)"

Examples​

Scenario 1: Suppose you want to grant access to users who have the claim grp equal to admin. You can define it like this:

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
  name: admin-access-subscription
  namespace: your-namespace
spec:
  applications:
    - appId: "your-application-id"
  apis:
    - name: "your-api"
  apiPlan:
    name: "standard-plan"
  claims: "Equals(`grp`, `admin`)"

In this example:

The claims expression: "Equals(`grp`, `admin`)" does the following:

  • Checks if the grp claim equals admin & grants access if it does.

Scenario 2: Suppose you want to grant access if the user belongs to the premium-users group or has the role manager.

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
  name: premium-access-subscription
  namespace: your-namespace
spec:
  applications:
    - appId: "your-application-id"
  apis:
    - name: "your-api"
  apiPlan:
    name: "premium-plan"
  claims: "Contains(`groups`, `premium-users`) || Equals(`role`, `manager`)"

In this example:

The claims expression: Contains(`groups`, `premium-users`) || Equals(`role`, `manager`) does the following:

  • Checks if the groups claim contains `premium-users & grants access if it does.
  • Checks if the role claim equals manager & grants access if it does.
Claim References

Reference claims directly by their key names as they appear in the token. Example: roles, groups, email, department

API Selector​

You can use apiSelector to dynamically include APIs based on labels in your Managed Subscriptions.

apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
  name: weather-app-subscription
  namespace: apps
spec:
  applications:
    - appId: "weather-app"
  apiSelector:
    matchLabels:
      category: weather
  apiPlan:
    name: standard-plan
  weight: 100
Read More

Please refer to the detailed documentation about Label selectors.

OperationFilter​

By default, when you grant access to an API through a ManagedSubscription, all of its operations are accessible to the users or applications specified. However, you can use the operationFilter to limit access to a specific subset of operations within the API.

This feature allows you to selectively grant access to predefined sets of operations, known as operationSets, which are specified in the API definition. By referencing these operationSets in the operationFilter, you gain fine-grained control over API exposure, enabling precise management of which operations are:

  • Visible on the Developer Portal (when using operationFilter in APICatalogItem).
  • Consumable by applications (when using operationFilter in ManagedSubscription).

Example​

In this example, we have an API called my-api with two operationSets: get-employees and get-payrolls. We want to:

  • Visibility: Allow users in the intern group to see my-api on the Developer Portal, but only with specified operations.
  • Consumption: Grant specific applications owned by interns access to my-api, restricted to the same operations.
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: my-api
  namespace: apps
spec:
  openApiSpec:
    path: /openapi.yaml
    operationSets:
      - name: get-employees
        matchers:
          methods: ["GET"]
          path: "/employees"
      - name: get-payrolls
        matchers:
          methods: ["GET"]
          path: "/payrolls"

Managing Overlapping Subscriptions​

When multiple Managed Subscriptions apply to the same application and API, Traefik Hub determines which subscription to enforce based on the weight field.

  • Higher Weight Takes Precedence: The subscription with the higher weight value is enforced.
  • Equal Weights: If weights are equal, alphabetical order of the Managed Subscription names determines precedence.

Frequently asked questions​

  • How do I handle backward compatibility?

    Existing APIAccess resources will continue to function for a given period of time. However, it’s recommended to transition to ManagedSubscription and APICatalogItem for better clarity and future compatibility.

  • How does ManagedSubscription differ from APIAccess?

    • APIAccess: Combined both visibility (which APIs users can see) and consumption access.
    • ManagedSubscription: Focuses solely on granting consumption access to applications. Visibility is now handled by APICatalogItem.

  • Can applications be created programmatically?

    Currently, applications are created via the Developer Portal.

  • Can I grant access to multiple APIs or API bundles?

    Yes, you can specify multiple APIs or use apiBundles to include groups of APIs in a Managed Subscription.

    apis:
    - name: weather-api
    - name: forecast-api
    apiBundles:
      - name: weather-bundle

  • How do I define consumption policies?

    Consumption policies are defined in APIPlan resources, which include rate limits and quotas.

    apiVersion: hub.traefik.io/v1alpha1
    kind: APIPlan
    metadata:
      name: standard-plan
      namespace: your-namespace
    spec:
      title: "Standard Plan"
      description: "Standard rate limits and quotas"
      rateLimit:
        limit: 10
        period: 1s
      quota:
        limit: 1000
        period: 720h # Approximately 30 days

  • Is there a limit to the number of APIs and API Bundles in a Managed Subscription?

    Yes, you can specify up to 100 APIs and 100 API Bundles per APICatalogItem. However, this limit is only on the apis and apiBundles field, you can select has many objects as you wish with selectors.

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 the API object in its dedicated section.
  • Learn more about the APIPlan resource in its dedicated section.
  • Learn more about APICatalogItem resource in its dedicated section.