Skip to main content

API Access

Manage access to your APIs.

Introduction​

API owners need to control access to their APIs, deciding who can use them and how. This is where the APIAccess resource comes in handy. By creating an APIAccess object and linking it to specific user groups and targeted APIs, owners can precisely manage access control to their APIs.

APIAccess behaviour​

Basic Usage​

Let's start with a basic example. Suppose you want to grant the customer user group access to the flight-api API. Here's how you can achieve that:

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: flight-customer
  namespace: apps
spec:
  groups:
    - customer
  apis:
    - name: flight-api
  apiPlan:
    name: std-plan
  weight: 100

Configuration options​

FieldDescriptionRequiredDefault
groupsList of user groups to grant accessYes
apisList of APIs to grant accessYes
apiPlanReferences the API PlanNo
weightDetermines the priority when multiple APIAccess resources overlap.NoDefault value is 0 when not set
warning

The APIAccess, APIPlan and the API must all exist in the same namespace.

Weight​

The weight field in the APIAccess resource allows you to prioritize access policies when a user belongs to multiple groups that have access to the same API. A higher weight value grants higher priority, meaning its associated APIPlan will take precedence over others with lower weights.

Key Points:

  • Priority Management: When multiple APIAccess resources apply to the same user and API, the one with the highest weight determines the enforced API Plan.
  • Default Behavior: If weight is not set, it defaults to 0. Resources with higher weights override those with lower or default weights.
  • Conflict Resolution: In cases where multiple APIAccess resources have the same weight, the system may use alphabetical order of the resource names to determine precedence.

Configuration Example​

Consider a scenario where a user belongs to both the standard and vip groups, each with different access policies for the same API. By assigning a higher weight to the vip group's APIAccess, you ensure that the vip plan is enforced over the standard one.

Define the API Plan
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: standard-plan
  namespace: default
spec:
  title: "Standard Plan"
  description: "Standard API access with basic rate limits."
  rateLimit:
    limit: 5
    period: 1s
  quota:
    limit: 10000
    period: 750h # 1 month
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: vip-plan
  namespace: default
spec:
  title: "VIP Plan"
  description: "VIP API access with enhanced rate limits and quotas."
  rateLimit:
    limit: 20
    period: 1s
  quota:
    limit: 50000
    period: 750h # 1 month

Outcome​

A user who belongs to both the standard and vip groups will have the vip-plan enforced for my-api due to its higher weight. This allows VIP users to benefit from enhanced rate limits and quotas without being constrained by the standard plan.

Everyone​

To allow every authenticated user to access an API, set the everyone option to true.

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: flight-everyone
spec:
  everyone: true
  apis:
    - name: flight-api
info

When Users / Consumers belong to multiple groups, they will inherit access from each group they belong to. Please refer to the documentation about user management for more information.

API Selector​

There are 2 ways to select APIs within your APIAccess:

  • Reference the targeted API names in the apis fields as shown in the example above.
  • Alternatively, you can select multiple APIs using the advanced apiSelector mechanism.

Let's add some labels on your API objects and use standard Kubernetes labels selectors in APIAccesses:

apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: flight-api
  namespace: apps
  labels:
    area: customers
    module: erp
spec:
  openApiSpec:
    path: /openapi.yaml
note

Multiple APIAccess objects can select the same APIs.

Advanced Selector Examples​

spec:
  // no apiSelector
Read More

Please refer to the detailed documentation about Label selectors.

Combining Selectors and API Names​

The following example combines API selection by name, matchLabels and matchExpressions. The selected APIs will include "my-api-1", "my-api-2" and all APIs with the "product" area label set, along with an audience of either "dev" or "admin".

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: admin-access
  namespace: apps
spec:
  groups:
    - support
  apis:
    - name: my-api-1
    - name: my-api-2
  apiSelector:
    matchLabels:
      area: product
    matchExpressions:
      - operator: in
        key: audience
        value: ["dev", "admin"]

OperationFilter​

By default, when granting access to an API for a group of users, all of its operations are accessible. However, you can use the operationFilter to limit exposure to a subset of operations. This feature allows you to selectively grant access to a defined set of operations, as specified in the API, using operationSets. The feature provides fine-grained control over API exposure, enabling precise management of which operations are accessible.

note

When you add an operationFilter to an APIAccess, it applies to every API of this APIAccess.

To simultaneously expose all and selected operations of your APIs, you need to use two distinct APIAccess objects: one for exposing all operations; the other for exposing selected operations, that is, to apply operation sets/filters. You can leverage both the UI or the Hub Static Analyzer that explain in details how accesses will propagate.

If an operation-filtering APIAccess and a non-granular APIAccess overlap, the non-granular will take precedence and provide full access to that API.

Example​

In the following example, the group intern has permissions for two operationSets: get-employees and get-payrolls, which are defined in the API Object.

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: intern-api
  namespace: apps
spec:
  groups:
    - intern
  apis:
    - name: my-api
  operationFilter:
    include:
      - get-employees
      - get-payrolls

Related Content​