feat: add API key authentication support

[aminghadersohi]

Summary

Add API key authentication support to Flask-AppBuilder, allowing users to create and manage long-lived API keys that work with the existing @protect() decorator and RBAC system.

Motivation

API key authentication is a common requirement for programmatic access to applications built with Flask-AppBuilder. Currently, FAB supports session-based and JWT authentication, but lacks support for API keys which are essential for:

• CI/CD pipelines that need to interact with protected APIs
• External integrations (e.g., MCP services) that need persistent authentication
• Automated tools and scripts that need long-lived credentials without JWT refresh complexity

This feature was discussed in the context of Apache Superset's API key authentication needs (see apache/superset#36173 and the related SIP discussion). The community agreed that implementing API key auth at the FAB layer provides the best architecture.

Changes

New Model: ApiKey (ab_api_key table)

• Columns: id, uuid, name, key_hash, key_prefix, user_id (FK), scopes, active, created_on, expires_on, revoked_on, last_used_on
• Keys are hashed with werkzeug before storage (plaintext shown only at creation)
• Prefix-based lookup for efficient validation (e.g., sst_)

Security Manager Methods

• validate_api_key(api_key_string) - lookup by prefix, verify hash, update last_used_on, set g.user
• create_api_key(user, name, scopes, expires_on) - generate key with secrets.token_urlsafe
• revoke_api_key(uuid) - set revoked_on timestamp
• find_api_keys_for_user(user_id) / get_api_key_by_uuid(uuid) - query methods

@protect() Decorator Integration

• API key auth check added before JWT verification
• When an API key prefix is detected in Authorization: Bearer, it's a deterministic auth path (validate → allow/deny, never falls through to JWT)
• Sets g.user and g._api_key_user flag for downstream access checks

CRUD API Endpoints (/api/v1/security/api_keys/)

• GET / - list current user's keys
• POST / - create a new key (returns plaintext once)
• GET /<uuid> - get key info (no plaintext)
• DELETE /<uuid> - revoke a key

Permission Auto-Registration

• register_views() explicitly calls add_permissions_view() after registering ApiKeyApi
• Ensures permissions are created even when AppBuilder(update_perms=False) (as Superset uses)
• Idempotent — safe when update_perms=True (permissions already exist)

Configuration

• FAB_API_KEY_ENABLED (default: False) - enable/disable the feature
• FAB_API_KEY_PREFIXES (default: ["sst_"]) - recognized key prefixes

Testing Instructions

Prerequisites

pip install -e .

Run Tests

python -m pytest tests/security/test_api_key.py -v

Manual Testing

1. Create a FAB app with FAB_API_KEY_ENABLED = True in config
2. Get a JWT token via /api/v1/security/login
3. Create an API key:

   curl -X POST http://localhost:5000/api/v1/security/api_keys/ \
     -H "Authorization: Bearer <JWT>" \
     -H "Content-Type: application/json" \
     -d '{"name":"test-key"}'

4. Use the returned key on any @protect()-decorated endpoint:

   curl -H "Authorization: Bearer sst_<KEY>" http://localhost:5000/api/v1/<endpoint>/

5. Verify rejection scenarios:
   • No auth → 401
   • Invalid API key (sst_invalid) → 403
   • Revoked key → 403
   • Valid JWT → 200 (coexistence)

Tests

27 tests across 5 test classes:

• ApiKeyModelTestCase - model is_active property with various states
• ApiKeySecurityManagerTestCase - create, validate, revoke, find operations
• ApiKeyEndpointTestCase - CRUD endpoint tests
• ApiKeyProtectDecoratorTestCase - @protect() with API key Bearer header, last_used_on tracking
• ApiKeyPermissionsTestCase - permissions exist and work with update_perms=False

All tests pass.

Closes #2430

[codecov]

Codecov Report

❌ Patch coverage is 90.04149% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.90%. Comparing base (b69c8f1) to head (92d7393).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
flask_appbuilder/security/sqla/manager.py	82.92%	14 Missing ⚠️
flask_appbuilder/security/manager.py	73.33%	8 Missing ⚠️
flask_appbuilder/security/sqla/apis/api_key/api.py	98.38%	1 Missing ⚠️
flask_appbuilder/security/sqla/models.py	96.55%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2431      +/-   ##
==========================================
+ Coverage   79.86%   79.90%   +0.04%     
==========================================
  Files          76       81       +5     
  Lines        8726     9183     +457     
==========================================
+ Hits         6969     7338     +369     
- Misses       1757     1845      +88     

Flag	Coverage Δ
python	79.90% <90.04%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dpgaspar]

This PR adds API key auth to @Protect(), but never registers an API key security scheme in the OpenAPI spec. So Swagger UI has no idea API keys exist — users can't enter an API key in the "Authorize"
dialog.

To fix this, two things need to happen:

1. Register the scheme — in SecurityApi.add_apispec_components() (or in ApiKeyApi), add something like:

api_key_scheme = {"type": "http", "scheme": "bearer", "bearerFormat": "API Key"}
api_spec.components.security_scheme("api_key", api_key_scheme)

2. Advertise it on operations — in BaseApi.operation_helper(), change the security from just [{"jwt": []}] to include the alternative:

operation_spec["security"] = [{"jwt": []}, {"api_key": []}]

This tells Swagger UI that each endpoint accepts either a JWT or an API key (both via Authorization: Bearer ). The "Authorize" dialog will then show both options.

[dpgaspar]

@aminghadersohi can you add docs about this new feature also

[dpgaspar]

Let's distinguish between a valid key with no authorization from an invalid key:

  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)
      return self.response_403()

[aminghadersohi]

Done -- invalid key now returns response_401(), and a valid key without permission returns response_403(). Updated the test expectation to match.

[dpgaspar]

extract_api_key_from_request should be a "public" static method

[aminghadersohi]

Good call, renamed to extract_api_key_from_request (dropped the leading underscore).

[aminghadersohi]

Added docs in both docs/security.rst (new "Authentication: API Keys" section covering enabling, creating, using, and config options) and docs/rest_api.rst (new "API Key Authentication" subsection explaining usage and 401/403 behavior).

[dpgaspar]

Nice!!