API Access

Manage access to your APIs.

---

Introduction

The API Access object defines which groups can access which APIs or Collections.

info

Gateways will embed the API Accesses they can expose. API accesses that don't belong to any gateway will be of no effect.

Users and Groups

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

Managing API Access Using CRDs

The API Access object has several properties.

Field	Description	Required
groups	Name of the user group(s) with permissions for the API(s). Requires apiSelector.matchLabels, apiSelector.matchExpressions or a combination of both to select APIs.	Yes
apis.name	Select APIs based on names You can combine it with apiSelector.matchLabels and apiSelector.matchExpressions. See Labels and Selectors.	No
apis.namespace	Name of the Kubernetes Namespace used by the API(s) defined in apis.name. This is required for apis.name.	No
operationFilter.include	Allow API operations which are configured via an operationSet for one or multiple group(s).	No
apiSelector.matchLabels	Select APIs based on label matching: Equality-Based Requirements.	No
apiSelector.matchExpressions	Select APIs based on advanced label expressions: Set-Based Requirements.	No
apiCollections	Select API Collections based on names.	No
apiCollectionSelector.matchLabels	Select API Collections based on label matching: Equality-Based Requirements	No
apiCollectionSelector.matchExpressions	Select API Collections based on advanced label expressions: Set-Based Requirements.	No

OperationFilter

By default, when an API is granted to a group of users, all of its operations become accessible. If you only want to expose a specific subset of operations, you can utilize the operationFilter.
This feature enables you to selectively grant access to a defined set of operations, as specified in the API, through the use of operationSets definitions.
This provides fine-grained control over API exposure, allowing you to precisely manage which operations are accessible.

note

When you configure an operationFilter on an APIAccess, it is effective for all the APIs selected by this APIAccess.

To expose APIs in their entirety and APIs with selected operations, you must use two APIAccess objects.
One is for publishing the whole API, and one is for the operation sets/filters.
This way, both the whole APIs and the selected operations will be available to the user as intended.

In case of an overlap between an operation filtering APIAccess and a non-granular APIAccess, the non-granular will be the stronger, providing all access to that API.

Examples

All examples below show how to give users from group support credentials to APIs.

Using Labels

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: customer-support
spec:
  groups:
    - support
  apiSelector:
    matchLabels:
      area: customers

Using API Name

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: customer-support
spec:
  groups:
    - support
  apis:
    - name: my-api-1
      namespace: my-ns
    - name: my-api-2
      namespace: my-ns

API Collections

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: customer-support
spec:
  groups:
    - support
  apiCollections:
    - name: crm-all

Combining Selectors and API Names

# Example of combing selecting APIs by `name`, `matchLabels` and `matchExpressions`.
# The selected APIs will be "my-api-1", "my-api-2" and all APIs with the area Label sets to "product" and audience either "dev" or "admin".
apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: admin-access
spec:
  groups:
    - support
  apis:
    - name: my-api-1
      namespace: my-ns
    - name: my-api-2
      namespace: my-ns
  apiSelector:
    matchLabels:
      area: product
    matchExpressions:
      - operator: in
        key: audience
        value: ["dev", "admin"]

Operation Filter

The group *intern* has permissions for two operationSets, *getEmployees* and *getPayrolls*

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: intern-api
spec:
  groups:
    - intern
  apis:
    - name: my-api
      namespace: my-ns
      # Using operationFilters to allow access only for two specific operationSets, operationSets are configured as part of the API or API versioning configuration
  operationFilter:
    include:
      - getEmployees
      - getPayrolls

Selector Examples

This won't select any APIs

spec:
  // no apiSelector

This will select all APIs

spec:
  apiSelector: {}

Select all APIs where the label key equals the value

spec:
  apiSelector:
    key: value

Read More

For more information, please refer to detailed documentation about Label selectors.

---

Related Content

• Lean more about authentication & authorization
• Get familiar with users and groups management