Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Semantic layer agent API groundwork + auth (#68163)

Noah Moss731688891322
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index 4664bfe75f5..f766004d44f 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -2081,7 +2081,8 @@
enterprise/metabot-v3
{:team "Metabot"
- :api #{metabase-enterprise.metabot-v3.api
+ :api #{metabase-enterprise.metabot-v3.agent-api.api
+ metabase-enterprise.metabot-v3.api
metabase-enterprise.metabot-v3.client
metabase-enterprise.metabot-v3.core
metabase-enterprise.metabot-v3.init
@@ -2090,6 +2091,7 @@
api
app-db
audit-app
+ auth-identity
collections
config
documents
diff --git a/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj b/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj
index bdf10d368ec..94de4477478 100644
--- a/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj
+++ b/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj
@@ -26,6 +26,7 @@
[metabase-enterprise.gsheets.api :as gsheets.api]
[metabase-enterprise.library.api]
[metabase-enterprise.llm.api]
+ [metabase-enterprise.metabot-v3.agent-api.api]
[metabase-enterprise.metabot-v3.api]
[metabase-enterprise.metabot-v3.tools.api]
[metabase-enterprise.permission-debug.api]
@@ -45,7 +46,8 @@
[metabase.util.i18n :refer [deferred-tru]]))
(comment metabase-enterprise.advanced-config.api.logs/keep-me
- metabase-enterprise.llm.api/keep-me)
+ metabase-enterprise.llm.api/keep-me
+ metabase-enterprise.metabot-v3.agent-api.api/keep-me)
(def ^:private required-feature->message
{:advanced-permissions (deferred-tru "Advanced Permissions")
@@ -87,7 +89,8 @@
`/ee/<feature>/`).
TODO -- Please fix them! See #22687"
- {"/moderation-review" metabase-enterprise.content-verification.api.routes/routes
+ {"/agent" (premium-handler metabase-enterprise.metabot-v3.agent-api.api/routes :metabot-v3)
+ "/moderation-review" metabase-enterprise.content-verification.api.routes/routes
"/mt" metabase-enterprise.sandbox.api.routes/sandbox-routes
"/table" metabase-enterprise.sandbox.api.routes/sandbox-table-routes})
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj
new file mode 100644
index 00000000000..8b2bf026baa
--- /dev/null
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj
@@ -0,0 +1,121 @@
+(ns metabase-enterprise.metabot-v3.agent-api.api
+ "Customer-facing Agent API for headless BI applications.
+ Endpoints are versioned (e.g., /v1/search) and use standard HTTP semantics."
+ (:require
+ [clojure.string :as str]
+ [metabase.api.macros :as api.macros]
+ [metabase.api.routes.common :as api.routes.common]
+ [metabase.auth-identity.core :as auth-identity]
+ [metabase.request.core :as request]
+ [metabase.util :as u]
+ [toucan2.core :as t2]))
+
+;;; --------------------------------------------------- Endpoints ----------------------------------------------------
+
+(api.macros/defendpoint :get "/v1/ping" :- [:map [:message :string]]
+ "Health check endpoint for the Agent API."
+ []
+ {:message "pong"})
+
+;;; ------------------------------------------------- Authentication -------------------------------------------------
+;;
+;; The Agent API supports two authentication modes:
+;;
+;; 1. **Session-based**: Client exchanges JWT at `/auth/sso` endpoint to get a session token,
+;; then passes it via `X-Metabase-Session` header. The standard Metabase session middleware
+;; handles validation and expiration checking automatically.
+;;
+;; 2. **Stateless JWT**: Client passes a JWT via `Authorization: Bearer <jwt>` header.
+;; The JWT is validated using the configured shared secret and max-age settings.
+;; Good for simple integrations and one-off API calls.
+
+(defn- extract-bearer-token
+ "Extract the token from a Bearer authorization header."
+ [auth-header]
+ (when (and auth-header (str/starts-with? (u/lower-case-en auth-header) "bearer "))
+ (str/trim (subs auth-header 7))))
+
+(defn- error-response
+ "Create a 401 error response with structured JSON body."
+ [error-type message]
+ {:status 401
+ :headers {"Content-Type" "application/json"}
+ :body {:error error-type
+ :message message}})
+
+;;; -------------------------------------------- Stateless JWT Authentication --------------------------------------------
+
+(defn- authenticate-with-jwt
+ "Authenticate a request using a stateless JWT. Returns {:user <user>} on success,
+ or {:error <type> :message <msg>} on failure. Does NOT create a session.
+
+ Uses auth-identity/authenticate to validate the JWT, which reuses the same
+ implementation as the /auth/sso endpoint and handles all settings validation."
+ [token]
+ (let [result (auth-identity/authenticate :provider/jwt {:token token})]
+ (if (:success? result)
+ ;; JWT is valid - look up user from the email extracted by the JWT provider
+ ;; The provider uses jwt-attribute-email setting to extract the email from claims
+ (if-let [user (when-let [email (get-in result [:user-data :email])]
+ (t2/select-one :model/User :%lower.email (u/lower-case-en email) :is_active true))]
+ {:user user}
+ ;; Don't reveal whether the user exists or not - use same error as invalid JWT
+ {:error "invalid_jwt"
+ :message "Invalid or expired JWT token."})
+ ;; Authentication failed - map error to agent API format
+ (case (:error result)
+ :jwt-not-enabled {:error "jwt_not_configured"
+ :message "JWT authentication is not configured. Set the JWT shared secret in admin settings."}
+ ;; Default: use generic invalid JWT message (don't leak details)
+ {:error "invalid_jwt"
+ :message "Invalid or expired JWT token."}))))
+
+;;; -------------------------------------------------- Middleware ----------------------------------------------------
+
+(defn- enforce-authentication
+ "Middleware that ensures requests are authenticated.
+
+ Supports two authentication modes:
+ - **Session-based**: Uses `X-Metabase-Session` header, validated by standard Metabase
+ session middleware (which runs before this). If `:metabase-user-id` is set on the
+ request, the user is already authenticated.
+ - **Stateless JWT**: Uses `Authorization: Bearer <jwt>` header. The JWT is validated
+ using the same auth-identity system as the /auth/sso endpoint."
+ [handler]
+ (fn [{:keys [headers metabase-user-id] :as request} respond raise]
+ (cond
+ ;; Already authenticated via X-Metabase-Session (standard middleware handled it)
+ metabase-user-id
+ (handler request respond raise)
+
+ ;; Not authenticated via session - check for Bearer JWT
+ :else
+ (let [auth-header (get headers "authorization")
+ bearer-token (extract-bearer-token auth-header)]
+ (cond
+ ;; No authorization header and no session
+ (nil? auth-header)
+ (respond (error-response "missing_authorization"
+ "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."))
+
+ ;; Authorization header present but not Bearer format
+ (nil? bearer-token)
+ (respond (error-response "invalid_authorization_format"
+ "Authorization header must use Bearer scheme: Authorization: Bearer <jwt>"))
+
+ ;; Validate JWT
+ :else
+ (let [result (authenticate-with-jwt bearer-token)]
+ (if-let [user (:user result)]
+ (request/with-current-user (:id user)
+ (handler request respond raise))
+ (respond (error-response (:error result) (:message result))))))))))
+
+(def ^:private +auth
+ (api.routes.common/wrap-middleware-for-open-api-spec-generation enforce-authentication))
+
+;;; ---------------------------------------------------- Routes ------------------------------------------------------
+
+(def ^{:arglists '([request respond raise])} routes
+ "`/api/agent/` routes."
+ (api.macros/ns-handler *ns* +auth))
diff --git a/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj b/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj
new file mode 100644
index 00000000000..af737206a32
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj
@@ -0,0 +1,141 @@
+(ns metabase-enterprise.metabot-v3.agent-api.api-test
+ (:require
+ [buddy.sign.jwt :as jwt]
+ [clojure.test :refer :all]
+ [environ.core :as env]
+ [java-time.api :as t]
+ [metabase-enterprise.sso.test-setup :as sso.test-setup]
+ [metabase.session.models.session :as session.models]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.test.http-client :as client]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(defn- current-epoch-seconds []
+ (int (/ (System/currentTimeMillis) 1000)))
+
+(defn- sign-jwt
+ "Sign a JWT with the test secret. Automatically adds `iat` claim if not present,
+ which is required for max-age validation."
+ [claims]
+ (jwt/sign (merge {:iat (current-epoch-seconds)} claims) sso.test-setup/default-jwt-secret))
+
+(defmacro with-agent-api-setup!
+ "Sets up JWT authentication for Agent API tests.
+ Reuses the SSO JWT test setup which handles premium features and settings correctly."
+ [& body]
+ `(sso.test-setup/with-jwt-default-setup!
+ (mt/with-additional-premium-features #{:metabot-v3}
+ ~@body)))
+
+(defn- auth-headers
+ "Create authorization headers with a signed JWT for the given email."
+ ([]
+ (auth-headers "[email protected]"))
+ ([email]
+ {"authorization" (str "Bearer " (sign-jwt {:email email}))}))
+
+(deftest agent-api-jwt-auth-test
+ (with-agent-api-setup!
+ (testing "Valid JWT with email claim succeeds"
+ (is (= {:message "pong"}
+ (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers (auth-headers)}}))))
+
+ (testing "Email case insensitivity - uppercase email in token"
+ (is (= {:message "pong"}
+ (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers (auth-headers "[email protected]")}}))))
+
+ (testing "Email case insensitivity - mixed case email in token"
+ (is (= {:message "pong"}
+ (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers (auth-headers "[email protected]")}}))))
+
+ (testing "Bearer scheme is case-insensitive (uppercase BEARER)"
+ (let [token (sign-jwt {:email "[email protected]"})
+ response (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers {"authorization" (str "BEARER " token)}}})]
+ (is (= {:message "pong"}
+ response))))
+
+ (testing "Bearer scheme is case-insensitive (mixed case)"
+ (let [token (sign-jwt {:email "[email protected]"})
+ response (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers {"authorization" (str "BeArEr " token)}}})]
+ (is (= {:message "pong"}
+ response))))))
+
+(deftest agent-api-error-responses-test
+ (with-agent-api-setup!
+ (testing "Missing authorization header (no session, no JWT)"
+ (let [response (client/client :get 401 "agent/v1/ping")]
+ (is (= {:error "missing_authorization"
+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
+ response))))
+
+ (testing "Invalid authorization header format (not Bearer)"
+ (let [response (client/client :get 401 "agent/v1/ping"
+ {:request-options {:headers {"authorization" "Basic xyz"}}})]
+ (is (= {:error "invalid_authorization_format"
+ :message "Authorization header must use Bearer scheme: Authorization: Bearer <jwt>"}
+ response))))
+
+ (testing "Token with non-existent user returns same error as invalid token (no information disclosure)"
+ (is (= {:error "invalid_jwt"
+ :message "Invalid or expired JWT token."}
+ (client/client :get 401 "agent/v1/ping"
+ {:request-options {:headers (auth-headers "[email protected]")}}))))))
+
+(deftest agent-api-session-token-auth-test
+ (mt/test-helpers-set-global-values!
+ (mt/with-additional-premium-features #{:metabot-v3}
+ (testing "Session tokens via X-Metabase-Session header authenticate successfully"
+ (let [session-key (session.models/generate-session-key)
+ _ (t2/insert! :model/Session
+ {:id (session.models/generate-session-id)
+ :user_id (mt/user->id :rasta)
+ :session_key session-key})
+ response (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers {"x-metabase-session" session-key}}})]
+ (is (= {:message "pong"} response))))
+
+ (testing "Invalid session token returns 401"
+ (let [fake-session-key (str (random-uuid))
+ response (client/client :get 401 "agent/v1/ping"
+ {:request-options {:headers {"x-metabase-session" fake-session-key}}})]
+ ;; Invalid session means standard middleware doesn't set metabase-user-id,
+ ;; so our middleware sees no auth and returns missing_authorization
+ (is (= {:error "missing_authorization"
+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
+ response)))))))
+
+(deftest agent-api-inactive-user-test
+ (with-agent-api-setup!
+ (testing "JWT for deactivated user returns same error as invalid token (no information disclosure)"
+ (mt/with-temp [:model/User {email :email} {:is_active false}]
+ (is (= {:error "invalid_jwt"
+ :message "Invalid or expired JWT token."}
+ (client/client :get 401 "agent/v1/ping"
+ {:request-options {:headers (auth-headers email)}})))))))
+
+(deftest agent-api-expired-session-test
+ (testing "Expired sessions are rejected by the standard session middleware"
+ (mt/test-helpers-set-global-values!
+ (mt/with-additional-premium-features #{:metabot-v3}
+ ;; Set max-session-age to 1 minute for this test
+ (with-redefs [env/env (assoc env/env :max-session-age "1")]
+ (let [session-key (session.models/generate-session-key)
+ old-time (t/minus (t/instant) (t/minutes 2))]
+ (mt/with-temp [:model/Session _ {:user_id (mt/user->id :rasta)
+ :session_key session-key
+ :created_at old-time}]
+ (testing "Session older than max-session-age is rejected"
+ (is (= {:error "missing_authorization"
+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
+ (client/client :get 401 "agent/v1/ping"
+ {:request-options {:headers {"x-metabase-session" session-key}}})))))))))))