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
- Managed Application: Represents a consuming entity (for example, a mobile app, web app) that
requires access to APIs. Each managed application has a unique App ID (
appId
) used for identification and authorization. - Application: Represents a consuming entity (for example, a mobile app, web app) that requires access to APIs. Each application has a
unique App ID (
appId
) used for identification and authorization. Deprecated in favor of Managed Applications. - 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
.
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
ManagedApplications
: Define aManagedApplication
resource for each client application that will consume APIs. This resource identifies the application and enables API publishers to manage its access throughManagedSubscription
. - 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
ManagedApplication
and references it from aManagedSubscription
to grant access.
- Shares the
- 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.
- Uses the provided
- The Gateway checks the
appId
in the JWT to grant access. - The consumer doesn't need to log into the Developer Portal.
Scenario 2: Using Signing Key for JWT Generation
- API Publisher Actions:
- Creates a
ManagedApplication
in the cluster (appId = weather-app) and (optionally) pre-provisions an API key secret. - Creates a
ManagedSubscription
referencing theManagedApplication
and attaches the desired API Plan(s). - Sends the signing key (or client secret) and the
appId
to the consumer.
- Creates a
- Consumer Actions:
- Uses the signing key +
appId
to create JWTs. - Immediately invokes the API, no Portal login is required.
- Uses the signing key +
With Managed Applications, the consumer never needs to access the Developer Portal.
Creating a Managed Subscription
Managed Subscriptions are defined using the ManagedSubscription
Custom Resource Definition (CRD). Below is an example of how to create one.
You must always include an API Plan in a Managed Subscription.
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
- Weather API
- Forecast API
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: weather-api
namespace: your-namespace
spec: {} # Additional specifications for the weather API
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
name: forecast-api
namespace: your-namespace
spec: {} # Additional specifications for the forecast API
Step 2: Define the API Plans
- Standard Plan
- VIP Plan
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
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
name: vip-plan
namespace: your-namespace
spec:
title: "VIP Plan"
description: "Higher rate limits and quotas for VIP applications"
rateLimit:
limit: 20
period: 1s
quota:
limit: 2000
period: 720h # Approximately 30 days
Step 3: Create Managed Applications
- Android App
- IOS App
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedApplication
metadata:
name: android-app
namespace: apps
spec:
appId: android-app
owner: 67f67907ee260b44336a952e # Hub user UUID (sub/externalID)
notes: "For Android clients"
apiKeys:
- secretName: android-app-key
title: android-app-key
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedApplication
metadata:
name: ios-app
namespace: apps
spec:
appId: ios-app
owner: 67f67907ee260b44336a952e # Hub user UUID (sub/externalID)
notes: "For IOS clients"
apiKeys:
- secretName: ios-app-key
title: ios-app-key
Step 4: Define the Managed Subscriptions
- Subscription for weather-api
- Subscription for forecast-api
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
name: weather-subscription
namespace: your-namespace
spec:
managedApplications:
- name: android-app
- name: ios-app
apis:
- name: weather-api
apiPlan:
name: standard-plan
weight: 100
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
name: forecast-subscription
namespace: your-namespace
spec:
managedApplications:
- name: android-app
- name: ios-app
apis:
- name: forecast-api
apiPlan:
name: vip-plan
weight: 100
Configuration Options
Field | Description | Required |
---|---|---|
applications | A list of applications (by appId ) that the subscription applies to. Deprecated in favor of Managed Applications | No |
managedApplications | A list of Managed Applications that the subscription applies to. | No |
apis | A list of APIs that the applications can access. | Yes |
apiPlan | The 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
andios-app
can accessweather-api
under the standard-plan. - Both applications can access
forecast-api
under thevip-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
.
- Define the API Bundle
- Managed Subscription with the API Bundle
apiVersion: hub.traefik.io/v1alpha1
kind: APIBundle
metadata:
name: weather-bundle
namespace: your-namespace
spec:
apis:
- name: weather-api
- name: forecast-api
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
name: weather-bundle-subscription
namespace: your-namespace
spec:
managedApplications:
- name: android-app
- name: ios-app
apiBundles:
- name: weather-bundle
apiPlan:
name: vip-plan
weight: 100
Outcome
- Both applications can access all APIs within the
weather-bundle
under thevip-plan
. - All APIs of the
weather-bundle
will share the same quota & limit defined in thevip-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
.
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.
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 / Operator | Syntax | Description | Example |
---|---|---|---|
Equals | Equals(claimName, expectedValue) | Checks if the claim claimName equals expectedValue . | "Equals(`grp`, `admin`)" |
NotEquals | NotEquals(claimName, unexpectedValue) | Checks if the claim claimName does not equal unexpectedValue . | "NotEquals(`status`, `inactive`)" |
Contains | Contains(claimName, value) | Checks if the claim claimName (string or array) contains value . | "Contains(`roles`, `manager`)" |
Prefix | Prefix(claimName, prefix) | Checks if the claim claimName starts with prefix . | "Prefix(`email`, `admin@`)" |
OneOf | OneOf(claimName, value1, value2, ...) | Checks if the claim claimName equals any of the provided values (value1 , value2 , etc.). | "OneOf(`department`, `sales`, `marketing`)" |
SplitContains | SplitContains(claimName, separator, value) | Splits the claim claimName using separator and checks if any resulting element equals value . | "SplitContains(`scopes`, ` `, `read`)" |
AND Operator | expression1 && expression2 | Logical AND of two expressions; evaluates to true if both expressions are true . | "Equals(`grp`, `admin`) && Contains(`roles`, `manager`)" |
OR Operator | expression1 || expression2 | Logical OR of two expressions; evaluates to true if either expression is true . | "Equals(`grp`, `admin`) || Equals(`grp`, `superuser`)" |
NOT Operator | !expression | Logical 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:
- Managed Subscription with Claims
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
name: admin-access-subscription
namespace: your-namespace
spec:
managedApplications:
- name: "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 equalsadmin
& 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
.
- Managed Subscription with Claims
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
name: premium-access-subscription
namespace: your-namespace
spec:
managedApplications:
- name: "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.
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:
managedApplications:
- name: weather-app
apiSelector:
matchLabels:
category: weather
apiPlan:
name: standard-plan
weight: 100
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
inAPICatalogItem
). - Consumable by applications (when using
operationFilter
inManagedSubscription
).
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.
- API
- Managed Subscription
- APICatalogItem
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"
apiVersion: hub.traefik.io/v1alpha1
kind: ManagedSubscription
metadata:
name: intern-api-subscription
namespace: apps
spec:
managedApplications:
- name: intern-app-1
- name: intern-app-2
apis:
- name: my-api
apiPlan:
name: standard-plan
operationFilter:
include:
- get-employees
- get-payrolls
apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
name: intern-api-catalog
namespace: apps
spec:
groups:
- intern
apis:
- name: my-api
operationFilter:
include:
- get-employees
- get-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 toManagedSubscription
andAPICatalogItem
for better clarity and future compatibility. -
How does
ManagedSubscription
differ fromAPIAccess
?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 byAPICatalogItem
.
-
Can applications be created programmatically?
Yes, you can create a Managed Application and reference it in the
ManagedSubscription
resource. -
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 theapis
andapiBundles
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 APICatalogItem resource in its dedicated section.
- Learn more about the Managed Applications resource in its dedicated section.