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
warning

Both the APIAccess and the API must exist in the same namespace.

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​