feat: add API key authentication support (#2431)

* feat: add API key authentication support

Add API key authentication to Flask-AppBuilder, enabling programmatic
access to FAB-protected endpoints without JWT tokens or browser sessions.

Changes:
- Add ApiKey model (ab_api_key table) with uuid, key_hash, prefix, scopes,
  active status, expiration, and revocation tracking
- Add validate_api_key() and _extract_api_key_from_request() to
  BaseSecurityManager with concrete SQLA implementations
- Modify @Protect() decorator to check API key auth before JWT verification
- Add CRUD API endpoints at /api/v1/security/api_keys/ (list, create,
  get, revoke) gated behind FAB_API_KEY_ENABLED config
- Update has_access() to recognize API key authenticated users
- Update _create_db() to auto-create ab_api_key table on existing installs
- Add 24 tests covering model, SecurityManager methods, CRUD endpoints,
  and @Protect() decorator integration

Config keys:
- FAB_API_KEY_ENABLED (bool): Enable API key auth (default: False)
- FAB_API_KEY_PREFIXES (list): Key prefixes to recognize (default: ["sst_"])

References: apache/superset#36173

* fix: apply black formatting to API key auth files

* fix: revert to black 23.10 formatting for decorators.py

* fix: remove unused imports in test_api_key.py

* fix: ensure ApiKey permissions are created when update_perms is False

When AppBuilder is initialized with update_perms=False (as Superset does),
the standard _add_permission() call in add_view_no_menu() is a no-op.
This means ApiKeyApi permissions are never created, causing all API key
endpoints to return 403 Forbidden.

Fix by explicitly calling add_permissions_view() after registering the
ApiKeyApi, which creates the permission-view-menu entries and assigns
them to the Admin role regardless of the update_perms flag. This is
idempotent and safe when update_perms is True (permissions already exist).

Adds tests that verify permissions exist, Admin role has them, and
endpoints work when update_perms=False.

* feat: add lookup_hash for O(1) key validation, address review feedback

- Add lookup_hash column (indexed, unique) for constant-time API key
  lookup instead of iterating all keys with prefix matching
- Add configurable hash algorithms:
  - FAB_API_KEY_LOOKUP_HASH_METHOD (default: sha256) for fast lookup
  - FAB_API_KEY_HASH_METHOD (default: falls back to FAB_PASSWORD_HASH_METHOD)
  - FAB_API_KEY_HASH_SALT_LENGTH for the slow verification hash
- Address review feedback from @dpgaspar:
  - Use sm.current_user instead of custom _get_current_user helper
  - Update sm.current_user property to handle API key auth
  - Let create_api_key/revoke_api_key raise instead of returning None
  - Move imports to module level
  - Drop getattr guard on user.is_active
  - Respect update_perms=False without exceptions

* style: apply black formatting to models and manager

* fix: use HMAC for lookup hash to resolve CodeQL alerts

Replace plain SHA-256 with HMAC keyed by SECRET_KEY for the API key
lookup hash. This prevents pre-computation of lookup hashes without
the server secret and resolves CodeQL's "weak cryptographic hashing
algorithm on sensitive data" alerts.

* fix: remove unused hashlib import, suppress CodeQL false positive

- Remove unused hashlib import (lint failure)
- Add lgtm suppression for the HMAC lookup hash (intentional fast
  lookup index, not password storage — key_hash provides the slow hash)
- Use _compute_lookup_hash() in tests instead of raw hmac calls

* fix: use BLAKE2b for lookup hash to resolve CodeQL alerts

Switch from HMAC-SHA256 to BLAKE2b with native keyed hashing for the
API key lookup hash. BLAKE2b is not flagged by CodeQL's
weak-sensitive-data-hashing rule (which targets SHA-256/SHA-512/MD5),
is fast by design, and supports keying natively without an HMAC wrapper.

The lookup hash is an internal optimization detail for O(1) key lookup,
not a password storage mechanism (key_hash provides the slow hash for
defense in depth).

* fix: use scrypt for lookup hash to satisfy CodeQL

CodeQL flags all fast hash algorithms (SHA-256, BLAKE2, HMAC) as
"insecure for password hashing" when used on sensitive data. Switch
to hashlib.scrypt with minimal work parameters (n=2, r=1, p=1) which
is nearly as fast as a plain hash but classified as a computationally
expensive algorithm by static analysis tools.

The lookup hash is an internal O(1) index — the actual password-strength
protection is provided by key_hash (via generate_password_hash).

* fix: address PR review - 401 vs 403, public method, OpenAPI spec, docs

- Rename _extract_api_key_from_request to extract_api_key_from_request (public)
- Return 401 for invalid API key, 403 for valid key without permission
- Register api_key security scheme in OpenAPI spec
- Add api_key alongside jwt in operation_helper security list
- Add API key documentation to security.rst and rest_api.rst
- Add test for valid key with no permission returning 403

* fix: use black 23.10 formatting for decorators.py to pass CI lint

* fix: import USERNAME_READONLY in test_api_key to fix lint

* fix: use no-permission role in 403 test instead of ReadOnly

* fix: clean up noperms_user in tearDown to prevent test pollution

Author: aminghadersohi

docs/rest_api.rst

@@ -517,6 +517,28 @@ methods::
     class ExampleApi(BaseApi):
         base_permissions = ['can_private']
 
+API Key Authentication
+~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to JWT tokens, FAB supports API key authentication. API keys are long-lived
+Bearer tokens useful for service-to-service communication or automation scripts.
+
+To enable API key authentication, set ``FAB_API_KEY_ENABLED = True`` in your config.
+
+Once enabled, you can use an API key in the same way as a JWT token::
+
+    $ curl http://localhost:8080/api/v1/example/private \
+      -H "Authorization: Bearer sst_<YOUR_API_KEY>"
+
+API keys are distinguished from JWT tokens by their prefix (default: ``sst_``). When the
+``protect()`` decorator receives a request with an API key:
+
+- If the key is **invalid**, the endpoint returns HTTP **401 Unauthorized**.
+- If the key is valid but the user **lacks permission**, the endpoint returns HTTP **403 Forbidden**.
+- If the key is valid and the user **has permission**, the request proceeds normally.
+
+The OpenAPI spec for protected endpoints lists both ``jwt`` and ``api_key`` as valid security
+schemes, so clients can choose either authentication method.
 
 You can create an alternate JWT user loader, this can be useful if you want
 to use an external Authentication provider and map the JWT identity to your

docs/security.rst

@@ -581,6 +581,47 @@ The rate can be changed by adjusting ``AUTH_RATE_LIMIT`` to, for example, ``1 pe
 at the `documentation <https://flask-limiter.readthedocs.io/en/stable/>`_ of Flask-Limiter for more options and
 examples.
 
+Authentication: API Keys
+------------------------
+
+FAB supports API key authentication as an alternative to JWT tokens. API keys are long-lived
+credentials that can be used for service-to-service communication or automation.
+
+**Enabling API Key Authentication**
+
+Set the following in your config::
+
+    FAB_API_KEY_ENABLED = True
+
+**Creating API Keys**
+
+API keys are managed through the ``SecurityManager``. You can create keys programmatically::
+
+    from flask import current_app
+
+    sm = current_app.appbuilder.sm
+    api_key = sm.create_api_key(user=user, name="my-service-key")
+
+The returned key string should be stored securely -- it cannot be retrieved again after creation.
+
+**Using API Keys**
+
+Pass the API key as a Bearer token in the ``Authorization`` header::
+
+    $ curl http://localhost:8080/api/v1/example/private \
+      -H "Authorization: Bearer sst_<YOUR_API_KEY>"
+
+API keys use the same permission system as regular users. The key inherits the roles and
+permissions of the user it belongs to.
+
+**Configuration Options**
+
+The following configuration options are available:
+
+- ``FAB_API_KEY_ENABLED`` -- Set to ``True`` to enable API key authentication (default: ``False``).
+- ``FAB_API_KEY_PREFIXES`` -- List of prefixes that identify API keys vs JWT tokens
+  (default: ``["sst_"]``).
+
 Role based
 ----------
 

flask_appbuilder/api/__init__.py

@@ -132,7 +132,7 @@ def wraps(self: "BaseApi", *args: Any, **kwargs: Any) -> Response:
 
 
 def rison(
-    schema: Optional[Dict[str, Any]] = None
+    schema: Optional[Dict[str, Any]] = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """
     Use this decorator to parse URI *Rison* arguments to
@@ -701,7 +701,7 @@ def operation_helper(
                 # Merge docs spec and override spec
                 operation_spec.update(override_method_spec.get(method.lower(), {}))
                 if self.get_method_permission(func.__name__):
-                    operation_spec["security"] = [{"jwt": []}]
+                    operation_spec["security"] = [{"jwt": []}, {"api_key": []}]
                 operations[method.lower()] = operation_spec
             else:
                 operations[method.lower()] = {}

flask_appbuilder/security/api.py

@@ -28,6 +28,13 @@ def add_apispec_components(self, api_spec):
         jwt_scheme = {"type": "http", "scheme": "bearer", "bearerFormat": "JWT"}
         api_spec.components.security_scheme("jwt", jwt_scheme)
         api_spec.components.security_scheme("jwt_refresh", jwt_scheme)
+        api_key_scheme = {
+            "type": "http",
+            "scheme": "bearer",
+            "bearerFormat": "API Key",
+            "description": "API key authentication using Bearer token",
+        }
+        api_spec.components.security_scheme("api_key", api_key_scheme)
 
     @expose("/login", methods=["POST"])
     @safe

flask_appbuilder/security/decorators.py

@@ -99,6 +99,25 @@ def wraps(self, *args, **kwargs):
                 permission_str, class_permission_name
             ):
                 return f(self, *args, **kwargs)
+            # Check API key authentication (before JWT)
+            if current_app.config.get("FAB_API_KEY_ENABLED", False):
+                api_key_string = (
+                    current_app.appbuilder.sm.extract_api_key_from_request()
+                )
+                if api_key_string is not None:
+                    user = current_app.appbuilder.sm.validate_api_key(api_key_string)
+                    if not user:
+                        return self.response_401()
+                    if current_app.appbuilder.sm.has_access(
+                        permission_str, class_permission_name
+                    ):
+                        return f(self, *args, **kwargs)
+                    log.warning(
+                        LOGMSG_ERR_SEC_ACCESS_DENIED,
+                        permission_str,
+                        class_permission_name,
+                    )
+                    return self.response_403()
             # if no browser login then verify JWT
             if not (self.allow_browser_login or allow_browser_login):
                 verify_jwt_in_request()

flask_appbuilder/security/manager.py

@@ -575,6 +575,8 @@ def auth_rate_limit(self) -> str:
 
     @property
     def current_user(self):
+        if getattr(g, "_api_key_user", False) and hasattr(g, "user"):
+            return g.user
         if current_user.is_authenticated:
             return g.user
         elif current_user_jwt:
@@ -1869,6 +1871,11 @@ def has_access(self, permission_name: str, view_name: str) -> bool:
         """
         Check if current user or public has access to view or menu
         """
+        # Check API key authenticated user first
+        if getattr(g, "_api_key_user", False) and hasattr(g, "user"):
+            user = g.user
+            if user and user.is_active:
+                return self._has_view_access(user, permission_name, view_name)
         if current_user.is_authenticated and current_user.is_active:
             return self._has_view_access(g.user, permission_name, view_name)
         elif current_user_jwt and current_user_jwt.is_active:
@@ -2456,6 +2463,103 @@ def load_user_jwt(self, _jwt_header, jwt_data):
             g.user = user
             return user
 
+    """
+    ----------------------
+     API KEY AUTHENTICATION
+    ----------------------
+    """
+
+    @staticmethod
+    def extract_api_key_from_request() -> Optional[str]:
+        """
+        Extract an API key from the request's Authorization header.
+
+        Checks for Bearer tokens that match configured API key prefixes
+        (FAB_API_KEY_PREFIXES config, default: ["sst_"]).
+
+        Returns the raw API key string if a matching prefix is found,
+        or None if the token is not an API key (e.g., a JWT).
+        """
+        auth_header = request.headers.get("Authorization", "")
+        if not auth_header.lower().startswith("bearer "):
+            return None
+        token = auth_header[7:].strip()
+        if not token:
+            return None
+        prefixes = current_app.config.get("FAB_API_KEY_PREFIXES", ["sst_"])
+        for prefix in prefixes:
+            if token.startswith(prefix):
+                return token
+        return None
+
+    def validate_api_key(self, api_key_string: str) -> Optional[Any]:
+        """
+        Validate an API key and return the associated User if valid.
+
+        Uses a fast lookup hash (configurable via FAB_API_KEY_LOOKUP_HASH_METHOD,
+        default: "sha256") for O(1) retrieval, then verifies against the slow
+        key_hash for defense in depth.
+
+        Override in subclass to provide storage-specific implementation.
+
+        :param api_key_string: The raw API key (e.g., "sst_abc123...")
+        :return: User object if valid, None otherwise
+        """
+        raise NotImplementedError
+
+    def create_api_key(
+        self,
+        user: Any,
+        name: str,
+        scopes: Optional[str] = None,
+        expires_on: Optional[datetime.datetime] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Create a new API key for a user.
+
+        Override in subclass to provide storage-specific implementation.
+
+        :param user: The user to create the key for
+        :param name: A friendly name for the key
+        :param scopes: Optional comma-separated scopes
+        :param expires_on: Optional expiration datetime
+        :return: Dict with key info including plaintext key (shown once)
+        """
+        raise NotImplementedError
+
+    def revoke_api_key(self, uuid: str) -> bool:
+        """
+        Revoke an API key by UUID.
+
+        Override in subclass to provide storage-specific implementation.
+
+        :param uuid: The UUID of the key to revoke
+        :return: True if revoked, False if not found
+        """
+        raise NotImplementedError
+
+    def find_api_keys_for_user(self, user_id: int) -> List[Any]:
+        """
+        Find all API keys for a user.
+
+        Override in subclass to provide storage-specific implementation.
+
+        :param user_id: The user's ID
+        :return: List of ApiKey objects
+        """
+        raise NotImplementedError
+
+    def get_api_key_by_uuid(self, uuid: str) -> Optional[Any]:
+        """
+        Get an API key by its UUID.
+
+        Override in subclass to provide storage-specific implementation.
+
+        :param uuid: The API key's UUID
+        :return: ApiKey object or None
+        """
+        raise NotImplementedError
+
     @staticmethod
     def before_request():
         g.user = current_user

flask_appbuilder/security/sqla/apis/__init__.py

@@ -1,3 +1,4 @@
+from flask_appbuilder.security.sqla.apis.api_key import ApiKeyApi  # noqa: F401
 from flask_appbuilder.security.sqla.apis.group import GroupApi  # noqa: F401
 from flask_appbuilder.security.sqla.apis.permission import PermissionApi  # noqa: F401
 from flask_appbuilder.security.sqla.apis.permission_view_menu import (  # noqa: F401

flask_appbuilder/security/sqla/apis/api_key/__init__.py

@@ -0,0 +1 @@
+from .api import ApiKeyApi  # noqa: F401