@gleanwork/auth

Authenticate with Glean from the command line or JavaScript, with tenant discovery, OAuth login, and automatic token refresh.

Installation

Requires Node.js 22.12.0 or newer.

npm install @gleanwork/auth

The JavaScript API is ESM-only.

Quick Start

Sign in with your work email and request the scopes your application needs:

npx glean-auth login --email [email protected] --scopes search

Print the current token for a shell command or non-JavaScript application:

export GLEAN_API_TOKEN="$(
  npx glean-auth token --email [email protected] --scopes search
)"

You can also run the CLI without installing it in a project:

npx -y @gleanwork/auth login --email [email protected] --scopes search

CLI

| Command | Description | | -------- | -------------------------------------------------------------- | | login | Sign in with OAuth and save credentials. | | status | Show local authentication status without printing credentials. | | token | Print the current access token. | | logout | Remove the matching saved OAuth credentials. |

npx glean-auth status --email [email protected] --scopes search
npx glean-auth status --email [email protected] --scopes search --json
npx glean-auth token --email [email protected] --scopes search
npx glean-auth logout --email [email protected] --scopes search

token prints only the token and a trailing newline to stdout. It does not start an interactive login. Run login first or set GLEAN_API_TOKEN.

Options

| Option | Description | | ---------------------- | ------------------------------------------------------------------- | | --email <address> | Discover the Glean tenant associated with an email address. | | --server-url <url> | Use the complete Glean backend origin instead of tenant discovery. | | --scopes <scope,...> | Request OAuth scopes. This option is repeatable and case-sensitive. |

Use the lowercase scope names advertised by the Glean OAuth server, such as search, chat, or mcp.

Run npx glean-auth --help for shared options and the command list. Run npx glean-auth <command> --help for command-specific options.

Authentication

OAuth is the recommended authentication method. login uses Authorization Code with PKCE and opens a browser for approval. If the tenant permits Dynamic Client Registration, the CLI registers a client automatically. Set GLEAN_OAUTH_CLIENT_ID when an administrator has provisioned a public OAuth client instead.

For CI or another non-interactive environment, set a user-scoped API token and the Glean backend URL:

export GLEAN_SERVER_URL=https://your-company-be.glean.com
export GLEAN_API_TOKEN=your-api-token

A non-empty GLEAN_API_TOKEN takes precedence when the package retrieves a token. The package does not validate the scopes or expiration of an API token.

The CLI chooses a tenant in this order:

1. --server-url
2. --email
3. GLEAN_SERVER_URL

OAuth always requests openid and offline_access in addition to the scopes passed through --scopes. A saved OAuth grant is reused only when it includes every requested scope.

JavaScript API

The package exports two runtime functions and their supporting TypeScript types.

import { createGleanTokenProvider, discoverGleanTenant } from "@gleanwork/auth";

const tenant = await discoverGleanTenant("[email protected]");
const getAccessToken = createGleanTokenProvider({
  serverUrl: tenant.serverUrl,
  scopes: ["search"],
});

const token = await getAccessToken();

discoverGleanTenant(email) returns the authoritative backend origin and a display identity for the tenant associated with an email address. Canonical *-be.glean.com and custom vanity backend origins are preserved exactly.

When using --server-url or GLEAN_SERVER_URL, pass the complete backend origin shown under Server instance (QE) on the Glean About page. Do not pass the Glean web app URL or derive a backend hostname from it.

createGleanTokenProvider(options) returns a non-interactive () => Promise<string> callback. It uses GLEAN_API_TOKEN when set. Otherwise, it reuses or refreshes credentials created by glean-auth login.

The callback can be passed directly to the Glean TypeScript SDK:

import { Glean } from "@gleanwork/api-client";
import { createGleanTokenProvider } from "@gleanwork/auth";

const glean = new Glean({
  serverURL: "https://your-company-be.glean.com",
  apiToken: createGleanTokenProvider({
    serverUrl: "https://your-company-be.glean.com",
    scopes: ["search"],
  }),
});

Credential Storage

The CLI stores OAuth credentials under $XDG_STATE_HOME/glean-auth when XDG_STATE_HOME is an absolute path. Otherwise, it uses ~/.local/state/glean-auth.

On Unix, state directories use mode 0700 and credential files use mode 0600. The package does not read or write project .env files. status never prints tokens; token intentionally writes a token to stdout for scripts and pipelines.

Contributing

See CONTRIBUTING.md for development setup and quality checks.

License

MIT, see LICENSE.