Add `accessTokenFromEnv` authentication method

[kop]

Summary

Add a new authentication option accessTokenFromEnv that reads an access token from a specified environment variable at connection time.

Motivation

This would help in two scenarios:

1. Local development and quick prototyping — developers can export a short-lived token in their shell and immediately run scripts without wiring up a full service account flow.
2. Security-constrained environments — in setups where credentials (client ID/secret) cannot be stored on local machines, an externally-provisioned token injected via environment variable is the only viable auth path.

Proposed behavior

accessTokenFromEnv accepts a string — the name of the environment variable that holds the access token.

const connection = await firebolt.connect({
  auth: {
    accessTokenFromEnv: "FIREBOLT_TOKEN",
  },
  engineName: 'engine_name',
  account: 'account_name',
  database: 'database',
});

At connection time, the SDK reads process.env.FIREBOLT_TOKEN. If the variable is set and non-empty, its value is used as the access token (equivalent to passing accessToken directly).

Combining with other auth methods

Unlike other auth options, accessTokenFromEnv can be specified alongside client_id/client_secret. When both are present, accessTokenFromEnv takes priority if the environment variable is set; otherwise the SDK falls back to the client credentials flow:

const connection = await firebolt.connect({
  auth: {
    // Use process.env.FIREBOLT_TOKEN if set
    accessTokenFromEnv: "FIREBOLT_TOKEN",
    // Fall back to client credentials otherwise
    client_id: 'b1c4918c-e07e-4ab2-868b-9ae84f208d26',
    client_secret: 'secret',
  },
  engineName: 'engine_name',
  account: 'account_name',
  database: 'database',
});

Resolution order

1. If accessTokenFromEnv is specified and process.env[value] is set and non-empty → use it as the access token.
2. Otherwise, if client_id/client_secret are provided → use client credentials auth.
3. Otherwise → throw an authentication error.

Type changes

type ConnectionOptions = {
  auth: AccessTokenAuth | ClientCredentialsAuth | FireboltCoreAuth | EnvTokenAuth | EnvTokenWithFallbackAuth;
  // ...
};

type EnvTokenAuth = {
  accessTokenFromEnv: string;
};

type EnvTokenWithFallbackAuth = {
  accessTokenFromEnv: string;
  client_id: string;
  client_secret: string;
};

[ShahafCohenTarica]

Getting the token from an env var is great, but the fb cli also saves that token in the os keychain. Is it possible to make the SDK to retrieve the token from the os keychain (if it exists)?

If the keychain is problematic, then maybe support the cli to save the token in a local file and allow the SDK to read the token from the file.

[kop]

@ShahafCohenTarica, our team discussed retrieving tokens directly from the keychain, and this is definitely something we plan to support.

The main challenge is ensuring this works consistently across all the SDKs we support. That’s not entirely straightforward due to differences in available libraries and underlying technology stacks. That said, we do have a plan for how to address this.

In upcoming FB CLI releases, we’ll introduce the concept of named profiles. For example, you’ll be able to configure multiple connections (e.g., staging, production) and switch between them easily - similar to how kubectl contexts or aws --profile work.

All SDKs will also gain a new authentication method based on these named profiles. Instead of passing credentials directly, you’ll specify a profile name, and the SDK will use profiles managed by the FB CLI. This should eliminate the need to work with environment variables altogether.

That said, I’d prefer to treat this as a follow-up improvement. We haven’t fully finalized the design yet, and I want to avoid introducing potential breaking changes to the SDKs.