SQL: add support for API key to JDBC and CLI by luigidellaquila · Pull Request #142021 · elastic/elasticsearch

luigidellaquila · 2026-02-06T15:12:34Z

Adding support for API key authentication to SQL HTTP client, used by JDBC and CLI.
Also adding an option to use it in JDBC connection URL and as a CLI parameter

jdbc:es://http://server:9200/?apiKey=<encoded-api-key>

./bin/elasticsearch-sql-cli --apikey <encoded-api-key> https://some.server:9200

Developed using AI-assisted tooling

github-actions · 2026-02-06T15:14:27Z

🔍 Preview links for changed docs

github-actions · 2026-02-06T15:14:28Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

…sql/jdbc_api_key

elasticsearchmachine · 2026-02-09T14:54:23Z

Pinging @elastic/es-analytical-engine (Team:Analytics)

elasticsearchmachine · 2026-02-09T14:54:23Z

Hi @luigidellaquila, I've created a changelog YAML for you.

astefan · 2026-02-23T10:27:51Z

libs/cli/src/main/java/org/elasticsearch/cli/Command.java

        if (options.has(silentOption)) {
            terminal.setVerbosity(Terminal.Verbosity.SILENT);
-            loggerFactory.setRootLevel(Level.OFF);
+            if (loggerFactory != null) {


Why is this needed now but wasn't needed so far?

This is not a consequence of this PR.
The factory is null since #123742, so it started throwing NPE. I don't know why we didn't notice it before.
The problem is that our CLI does not depend on server, so we can't access LogConfigurator and LoggerFactoryImpl.
Let me see if we can do better, maybe we can setup a custom log factory

It's more complex than I thought.
SQL CLI runs as a shadow JAR, so I can't access LoggerFactory.setInstance() directly.
I'll open an issue, but I guess the null checks are enough to unblock the component

astefan · 2026-02-23T10:38:06Z

...sql/sql-client/src/main/java/org/elasticsearch/xpack/sql/client/ConnectionConfiguration.java

+        apiKey = settings.getProperty(AUTH_API_KEY);
+
+        // validate that only one authentication method is specified
+        if (StringUtils.hasText(apiKey) && StringUtils.hasText(user)) {


Shouldn't this validation also apply in other constructor as well?

astefan · 2026-02-23T10:40:46Z

docs/reference/query-languages/sql/sql-cli.md

 $ ./bin/elasticsearch-sql-cli https://sql_user:strongpassword@some.server:9200
 ```

+### API Key Authentication [sql-cli-apikey]


I am wondering about --apikey <value> on the command line being visible via ps aux or /proc/<pid>/cmdline. The docs mention not to combine API key with basic auth, but don't
warn about this security aspect. Should this be mentioned in docs, and provide alternative suggestions?

That's a good point. I'm adding a note to the docs.

astefan · 2026-02-23T10:43:07Z

docs/reference/query-languages/sql/sql-cli.md


+### API Key Authentication [sql-cli-apikey]
+
+As an alternative to basic authentication, you can use API key authentication with the `--apikey` option. API keys can be created using the [Create API key API](docs-content://deploy-manage/api-keys/elasticsearch-api-keys.md). The API key should be provided in its encoded form (the `encoded` value returned by the Create API key API):


--apiKey? (uppercase K)

This is for consistency, JDBC and CLI use all lowercase parameters.

astefan · 2026-02-23T10:43:25Z

docs/reference/query-languages/sql/sql-cli.md

+As an alternative to basic authentication, you can use API key authentication with the `--apikey` option. API keys can be created using the [Create API key API](docs-content://deploy-manage/api-keys/elasticsearch-api-keys.md). The API key should be provided in its encoded form (the `encoded` value returned by the Create API key API):
+
+```bash
+$ ./bin/elasticsearch-sql-cli --apikey <encoded-api-key> https://some.server:9200


Same here. Uppercase K?

Same as above

astefan · 2026-02-23T10:45:17Z

x-pack/plugin/sql/qa/server/src/main/java/org/elasticsearch/xpack/sql/qa/cli/EmbeddedCli.java

+    }
+
+    @SuppressWarnings("this-escape")
+    private EmbeddedCli(


I think only this constructor needs the @suppressWarnings.

astefan · 2026-02-23T10:48:18Z

...ql/qa/server/security/src/test/java/org/elasticsearch/xpack/sql/qa/security/CliApiKeyIT.java

@@ -0,0 +1,218 @@
+/*


I like comments in code, but in these test classes I think there are too many comments imo.

Let me remove the redundant comments

astefan · 2026-02-23T10:52:35Z

...ql/qa/server/security/src/test/java/org/elasticsearch/xpack/sql/qa/security/CliApiKeyIT.java

+        return cluster.split(",")[0];
+    }
+
+    private String createApiKey(String name, String body) throws IOException {


I think you should clean up these api keys when the test finishes (or fails midway) in an @After method.

astefan · 2026-02-23T10:53:12Z

...l/qa/server/security/src/test/java/org/elasticsearch/xpack/sql/qa/security/JdbcApiKeyIT.java

+        }
+    }
+
+    private String createApiKey(String name, String body) throws IOException {


Same here. You should clean up these api keys when the test finishes (or fails midway) in an @After method.

astefan

It's LGTM, but I would look into extracting common code from both CliApiKeyIT and JdbcApiKeyIT in a base class and extend that instead (like the clean up logic, the method that creates the api keys etc)

luigidellaquila · 2026-02-24T11:05:12Z

Thanks @astefan!

…on-sliced-reindex * upstream/main: Activity logging improvements (elastic#142901) Fix serialization of NodeGpuStatsResponse when no GPU is present (elastic#142937) Add doc on master elections in DistributedArchitectureGuide (elastic#142435) ESQL: Account for missing StubRelation due to SurrogateExpressions replacement (elastic#142882) Add BulkByScrollTask Serialization Tests (elastic#142697) Rebalance CI test partitions to reduce Part3 bottleneck (elastic#142930) Mute org.elasticsearch.xpack.esql.qa.multi_node.EsqlClientYamlIT test {p0=esql/40_tsdb/to_aggregate_metric_double with multi_values} elastic#142964 Bump OpenTelemetry dependencies (elastic#142323) SQL: add support for API key to JDBC and CLI (elastic#142021) Ensure requested capability exists (elastic#142695) Warn and fall back to local branches.json (elastic#142606) [CI] Mute testWithFetchFailures, testAddCompletionListenerScheduleErr… (elastic#142926) ESQL: Add support for ORC file format (elastic#142900) Update wolfi (versioned) (elastic#142948) Add BulkByScrollResponse Serialization Tests (elastic#142688) Run 25_id_generation with and without synthetic id (elastic#142770)

luigidellaquila added 3 commits February 6, 2026 11:46

SQL: Implement API key support

07bc38b

Fix logs

9576b86

API key placeholder

4a6ca7e

elasticsearchmachine added the v9.4.0 label Feb 6, 2026

elasticsearchmachine and others added 3 commits February 6, 2026 15:19

[CI] Auto commit changes from spotless

a262598

Fix getBytes()

1eeb34f

Merge remote-tracking branch 'luigidellaquila/sql/jdbc_api_key' into …

369b5e3

…sql/jdbc_api_key

luigidellaquila mentioned this pull request Feb 6, 2026

SQL: add project_routing to CLI #138965

Merged

Merge branch 'main' into sql/jdbc_api_key

6220e79

luigidellaquila marked this pull request as ready for review February 9, 2026 14:53

luigidellaquila added >enhancement :Analytics/SQL SQL querying labels Feb 9, 2026

luigidellaquila requested a review from bpintea February 9, 2026 14:54

elasticsearchmachine added the Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) label Feb 9, 2026

luigidellaquila added 2 commits February 9, 2026 15:54

Update docs/changelog/142021.yaml

dcf4ec5

Merge branch 'main' into sql/jdbc_api_key

6aaa188

luigidellaquila requested a review from a team as a code owner February 23, 2026 09:42

astefan reviewed Feb 23, 2026

View reviewed changes

luigidellaquila added 2 commits February 23, 2026 14:12

Implement review suggestions

acb87f6

Merge branch 'main' into sql/jdbc_api_key

11a99b1

astefan approved these changes Feb 24, 2026

View reviewed changes

Refactor tests

11c6571

Merge branch 'main' into sql/jdbc_api_key

9cd3dce

luigidellaquila enabled auto-merge (squash) February 24, 2026 11:05

Merge branch 'main' into sql/jdbc_api_key

ef9b518

bpintea approved these changes Feb 24, 2026

View reviewed changes

luigidellaquila merged commit 88ea038 into elastic:main Feb 24, 2026
35 checks passed

luigidellaquila mentioned this pull request Mar 2, 2026

API Key support on elasticsearch-sql-cli #106807

Closed


		### API Key Authentication [sql-cli-apikey]

		As an alternative to basic authentication, you can use API key authentication with the `--apikey` option. API keys can be created using the [Create API key API](docs-content://deploy-manage/api-keys/elasticsearch-api-keys.md). The API key should be provided in its encoded form (the `encoded` value returned by the Create API key API):

Conversation

luigidellaquila commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions bot commented Feb 6, 2026

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

elasticsearchmachine commented Feb 9, 2026

Uh oh!

elasticsearchmachine commented Feb 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

astefan left a comment

Choose a reason for hiding this comment

Uh oh!

luigidellaquila commented Feb 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

luigidellaquila commented Feb 6, 2026 •

edited

Loading

github-actions bot commented Feb 6, 2026 •

edited

Loading