@indigoai-us/hq-cli 5.47.12 → 5.47.14

package/dist/bin/hq-auth-refresh.d.ts

@@ -6,8 +6,9 @@
  * shell out to a plain binary instead of a subcommand. Equivalent to
  * `hq auth refresh`.
  *
- * Exit 0 on refresh, exit 1 if no cached session or refresh failed.
- * Writes the refreshed tokens to ~/.hq/cognito-tokens.json.
+ * Exit 0 if a valid session is ensured now (healthy cache hit, refresh, or
+ * machine-token mint). Exit 1 if no valid session could be ensured
+ * non-interactively.
  */
 export {};
 //# sourceMappingURL=hq-auth-refresh.d.ts.map

package/dist/bin/hq-auth-refresh.js

@@ -6,11 +6,12 @@
  * shell out to a plain binary instead of a subcommand. Equivalent to
  * `hq auth refresh`.
  *
- * Exit 0 on refresh, exit 1 if no cached session or refresh failed.
- * Writes the refreshed tokens to ~/.hq/cognito-tokens.json.
+ * Exit 0 if a valid session is ensured now (healthy cache hit, refresh, or
+ * machine-token mint). Exit 1 if no valid session could be ensured
+ * non-interactively.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="28774b80-becb-5fb9-b676-dee74c26d73d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="03d2c531-f620-5d93-a87b-9a87264ad77b")}catch(e){}}();
 import { initSentry, Sentry } from "../sentry.js";
 import { refreshCachedSession } from "../utils/cognito-session.js";
 initSentry();
@@ -37,4 +38,4 @@ initSentry();
     }
 })();
 //# sourceMappingURL=hq-auth-refresh.js.map
-//# debugId=28774b80-becb-5fb9-b676-dee74c26d73d
+//# debugId=03d2c531-f620-5d93-a87b-9a87264ad77b

package/dist/commands/api-keys.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerApiKeysCommand(program: Command): Command;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/commands/api-keys.js

@@ -0,0 +1,198 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c9f6fe34-9e38-5001-97b7-14b35c956330")}catch(e){}}();
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+function collectRepeatedOption(value, previous) {
+    return [...previous, value];
+}
+function formatMaybe(value) {
+    return value ?? "-";
+}
+function formatPrefixes(prefixes) {
+    return prefixes.length > 0 ? prefixes.join(", ") : "-";
+}
+function parsePermission(value) {
+    if (value === "read" || value === "write" || value === "admin") {
+        return value;
+    }
+    throw new Error(`Invalid permission '${value}'. Use one of: read, write, admin.`);
+}
+function parseExpires(expires) {
+    if (expires === undefined)
+        return undefined;
+    if (Number.isNaN(Date.parse(expires))) {
+        throw new Error(`Invalid --expires value '${expires}'. Use an ISO-8601 timestamp.`);
+    }
+    return expires;
+}
+async function readApiError(res, action) {
+    const body = (await res.json().catch(() => ({})));
+    const message = typeof body.message === "string"
+        ? body.message
+        : typeof body.error === "string"
+            ? body.error
+            : res.statusText;
+    if (res.status === 401) {
+        return "Not authenticated - please run `hq login`";
+    }
+    if (res.status === 403) {
+        return `Not authorized to ${action}`;
+    }
+    if (res.status === 404) {
+        return message || "API key not found";
+    }
+    if (res.status >= 500) {
+        return `Server error: ${message}`;
+    }
+    return message || `Request failed (${res.status})`;
+}
+function renderApiKeysTable(apiKeys) {
+    const rows = apiKeys.map((apiKey) => ({
+        keyId: apiKey.keyId,
+        name: apiKey.name,
+        permission: apiKey.scope.permission,
+        prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+        status: apiKey.status,
+        lastUsedAt: formatMaybe(apiKey.lastUsedAt),
+        expiresAt: formatMaybe(apiKey.expiresAt),
+    }));
+    const keyIdWidth = Math.max(6, ...rows.map((row) => row.keyId.length));
+    const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
+    const permissionWidth = Math.max(10, ...rows.map((row) => row.permission.length));
+    const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+    const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
+    const lastUsedWidth = Math.max(11, ...rows.map((row) => row.lastUsedAt.length));
+    const expiresWidth = Math.max(10, ...rows.map((row) => row.expiresAt.length));
+    const header = [
+        "KEY ID".padEnd(keyIdWidth),
+        "NAME".padEnd(nameWidth),
+        "PERMISSION".padEnd(permissionWidth),
+        "PREFIXES".padEnd(prefixesWidth),
+        "STATUS".padEnd(statusWidth),
+        "LAST USED".padEnd(lastUsedWidth),
+        "EXPIRES".padEnd(expiresWidth),
+    ].join("  ");
+    console.log(chalk.bold(header));
+    for (const row of rows) {
+        console.log([
+            row.keyId.padEnd(keyIdWidth),
+            row.name.padEnd(nameWidth),
+            row.permission.padEnd(permissionWidth),
+            row.prefixes.padEnd(prefixesWidth),
+            row.status.padEnd(statusWidth),
+            row.lastUsedAt.padEnd(lastUsedWidth),
+            row.expiresAt.padEnd(expiresWidth),
+        ].join("  "));
+    }
+}
+export function registerApiKeysCommand(program) {
+    const apiKeys = program
+        .command("api-keys")
+        .description("Manage vault API keys for CI and automation")
+        .option("--company <slug>", "Company slug (resolves to companyUid)");
+    apiKeys
+        .command("create")
+        .description("Create a new API key")
+        .requiredOption("--name <label>", "Human-readable label for the API key")
+        .option("--scope <prefix>", "Allowed prefix (repeatable)", collectRepeatedOption, [])
+        .option("--permission <level>", "Permission level: read | write | admin", "read")
+        .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
+        .action(async (opts) => {
+        try {
+            if (opts.scope.length === 0) {
+                console.error(chalk.red("Error: at least one --scope <prefix> is required."));
+                process.exit(1);
+            }
+            const permission = parsePermission(opts.permission);
+            const expiresAt = parseExpires(opts.expires);
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, apiKeys.opts().company);
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/api-keys",
+                method: "POST",
+                body: {
+                    companyUid,
+                    name: opts.name,
+                    allowedPrefixes: opts.scope,
+                    permission,
+                    ...(expiresAt ? { expiresAt } : {}),
+                },
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "create API keys"));
+            }
+            const data = (await res.json());
+            console.log(chalk.green("API key created."));
+            console.log(chalk.yellow("Store this key now - it won't be shown again:"));
+            console.log(`\n  ${data.key.value}\n`);
+            console.log(chalk.bold("Metadata"));
+            console.log(`  Key ID: ${data.apiKey.keyId}`);
+            console.log(`  Name: ${data.apiKey.name}`);
+            console.log(`  Company: ${data.apiKey.companyUid}`);
+            console.log(`  Permission: ${data.apiKey.scope.permission}`);
+            console.log(`  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`);
+            console.log(`  Status: ${data.apiKey.status}`);
+            console.log(`  Created: ${data.apiKey.createdAt}`);
+            console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
+            console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    apiKeys
+        .command("list")
+        .description("List API keys for a company")
+        .action(async () => {
+        try {
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, apiKeys.opts().company);
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/api-keys",
+                query: { companyUid },
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "list API keys"));
+            }
+            const data = (await res.json());
+            if (data.apiKeys.length === 0) {
+                console.log(chalk.dim("No API keys found."));
+                return;
+            }
+            renderApiKeysTable(data.apiKeys);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    apiKeys
+        .command("revoke <keyId>")
+        .description("Revoke an API key")
+        .action(async (keyId) => {
+        try {
+            const token = await ensureCognitoToken();
+            const res = await vaultApiFetch({
+                token,
+                path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,
+                method: "POST",
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "revoke this API key"));
+            }
+            const data = (await res.json());
+            console.log(chalk.green(`Revoked API key '${data.apiKey.keyId}'`));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    return apiKeys;
+}
+//# sourceMappingURL=api-keys.js.map
+//# debugId=c9f6fe34-9e38-5001-97b7-14b35c956330

package/dist/commands/auth.d.ts

@@ -4,13 +4,13 @@
  * Subcommands:
  *   hq auth login     — open the Cognito Hosted UI in the browser and cache tokens
  *   hq auth logout    — clear the cached HQ session
- *   hq auth refresh   — refresh the cached Cognito session (non-interactive)
+ *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
- * session is kept fresh by `hq auth refresh` / `hq-auth-refresh` and consumed
+ * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
  */
 import { Command } from "commander";

package/dist/commands/auth.js

@@ -4,17 +4,17 @@
  * Subcommands:
  *   hq auth login     — open the Cognito Hosted UI in the browser and cache tokens
  *   hq auth logout    — clear the cached HQ session
- *   hq auth refresh   — refresh the cached Cognito session (non-interactive)
+ *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
- * session is kept fresh by `hq auth refresh` / `hq-auth-refresh` and consumed
+ * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b9690c95-1d23-5c58-8cb3-0e3bdc8b35e8")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="66a74720-f5d1-58ed-93fd-ead15fc18146")}catch(e){}}();
 import chalk from "chalk";
 import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
 import { refreshCachedSession, } from "../utils/cognito-session.js";
@@ -98,14 +98,14 @@ export function registerAuthCommands(program) {
     });
     authCmd
         .command("refresh")
-        .description("Refresh the cached Cognito session using the stored refresh token")
+        .description("Ensure a valid cached Cognito session (refresh only if expiring; no-op if already valid)")
         .action(async () => {
         const result = await refreshCachedSession();
         if (result.refreshed) {
-            console.log(chalk.green("HQ session refreshed"));
+            console.log(chalk.green("HQ session ensured"));
             return;
         }
-        console.error(chalk.yellow(`No refresh: ${result.reason ?? "unknown"}`));
+        console.error(chalk.yellow(`No valid session: ${result.reason ?? "unknown"}`));
         process.exit(1);
     });
     authCmd
@@ -136,4 +136,4 @@ export function registerAuthCommands(program) {
     });
 }
 //# sourceMappingURL=auth.js.map
-//# debugId=b9690c95-1d23-5c58-8cb3-0e3bdc8b35e8
+//# debugId=66a74720-f5d1-58ed-93fd-ead15fc18146

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6fa5c878-2930-5b94-bc7c-5deea8795218")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="964b8c71-056c-51fb-893a-d51f8f6ad5d9")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -28,6 +28,7 @@ import { registerPublishCommand } from "./commands/publish.js";
 import { registerCreatorsCommand } from "./commands/creators.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiKeysCommand } from "./commands/api-keys.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
@@ -117,6 +118,8 @@ registerWhoamiCommand(program);
 registerAuthCommands(program);
 // Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
 registerSecretsCommand(program);
+// API key management (subcommand group — hq api-keys create|list|revoke)
+registerApiKeysCommand(program);
 // Schema-driven dev runner — hq run [options] -- <cmd>
 registerRunCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
@@ -177,4 +180,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=6fa5c878-2930-5b94-bc7c-5deea8795218
+//# debugId=964b8c71-056c-51fb-893a-d51f8f6ad5d9

package/dist/utils/cognito-session.d.ts

@@ -109,10 +109,12 @@ export declare const CLI_CLIENT_INFO: ClientInfo;
 /** Build a VaultServiceConfig with the given access token. */
 export declare function buildVaultConfig(authToken: string): VaultServiceConfig;
 /**
- * Refresh the cached Cognito session once and return the result. Used by
- * `hq auth refresh` and the `hq-auth-refresh` bin. Never opens a browser —
- * if no cached tokens exist or the refresh fails, returns `refreshed: false`
- * with a reason string so the caller can decide what to do.
+ * Ensure a valid cached Cognito session exists right now, non-interactively,
+ * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
+ * bin. `refreshed: true` means a valid session is ensured now from a healthy
+ * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
+ * means no valid session could be ensured non-interactively; the caller gets a
+ * reason string and can decide what to do next. Never opens a browser.
  */
 export declare function refreshCachedSession(): Promise<{
     refreshed: boolean;

package/dist/utils/cognito-session.js

@@ -19,13 +19,13 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="21e260f0-50fd-54c7-944a-c15630c42f3e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ab9733a5-3984-553b-8fcc-91b86d112c79")}catch(e){}}();
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
-import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, mintMachineTokens, } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 export const DEFAULT_COGNITO = {
     region: process.env.AWS_REGION ?? "us-east-1",
@@ -334,17 +334,19 @@ export function buildVaultConfig(authToken) {
     };
 }
 /**
- * Refresh the cached Cognito session once and return the result. Used by
- * `hq auth refresh` and the `hq-auth-refresh` bin. Never opens a browser —
- * if no cached tokens exist or the refresh fails, returns `refreshed: false`
- * with a reason string so the caller can decide what to do.
+ * Ensure a valid cached Cognito session exists right now, non-interactively,
+ * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
+ * bin. `refreshed: true` means a valid session is ensured now from a healthy
+ * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
+ * means no valid session could be ensured non-interactively; the caller gets a
+ * reason string and can decide what to do next. Never opens a browser.
  */
 export async function refreshCachedSession() {
-    // Machine identities have no refresh token — a "refresh" is a fresh mint
-    // from the long-lived machine creds.
+    // Machine identities have no refresh token; ensure a valid cached machine
+    // session without forcing a re-mint when the cache is already healthy.
     if (isMachineIdentity()) {
         try {
-            await mintMachineTokens(DEFAULT_COGNITO);
+            await getValidMachineTokens(DEFAULT_COGNITO);
             return { refreshed: true };
         }
         catch (err) {
@@ -358,6 +360,9 @@ export async function refreshCachedSession() {
     if (!cached) {
         return { refreshed: false, reason: "no cached session" };
     }
+    if (!isExpiring(cached, 120)) {
+        return { refreshed: true };
+    }
     try {
         await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
         return { refreshed: true };
@@ -370,4 +375,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=21e260f0-50fd-54c7-944a-c15630c42f3e
+//# debugId=ab9733a5-3984-553b-8fcc-91b86d112c79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.47.12",
+  "version": "5.47.14",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/bin/hq-auth-refresh.ts

@@ -7,8 +7,9 @@
  * shell out to a plain binary instead of a subcommand. Equivalent to
  * `hq auth refresh`.
  *
- * Exit 0 on refresh, exit 1 if no cached session or refresh failed.
- * Writes the refreshed tokens to ~/.hq/cognito-tokens.json.
+ * Exit 0 if a valid session is ensured now (healthy cache hit, refresh, or
+ * machine-token mint). Exit 1 if no valid session could be ensured
+ * non-interactively.
  */
 
 import { initSentry, Sentry } from "../sentry.js";

package/src/commands/api-keys.test.ts

@@ -0,0 +1,217 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+vi.mock("./secrets.js", async (importOriginal) => {
+  const original = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...original,
+    getCompanyUid: vi.fn(async () => "cmp_acme"),
+    vaultApiFetch: vi.fn(),
+  };
+});
+
+import { Command } from "commander";
+import { registerApiKeysCommand } from "./api-keys.js";
+import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: () => undefined,
+    writeErr: () => undefined,
+  });
+  registerApiKeysCommand(program);
+  return program;
+}
+
+let logSpy: MockInstance<typeof console.log>;
+let errSpy: MockInstance<typeof console.error>;
+let exitSpy: MockInstance<typeof process.exit>;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+  errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  exitSpy = vi
+    .spyOn(process, "exit")
+    .mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("hq api-keys create", () => {
+  it("POSTs the expected body and prints the raw key exactly once", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        apiKey: {
+          keyId: "key_123",
+          companyUid: "cmp_acme",
+          name: "CI key",
+          scope: {
+            allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
+            permission: "read",
+          },
+          status: "active",
+          createdAt: "2026-06-19T12:00:00.000Z",
+          lastUsedAt: null,
+          expiresAt: "2026-07-01T00:00:00.000Z",
+        },
+        key: { value: "hqk_test_secret_value" },
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        "api-keys",
+        "create",
+        "--company",
+        "indigo",
+        "--name",
+        "CI key",
+        "--scope",
+        "HQ_PRO/HQ_PROD",
+        "--scope",
+        "HQ_PRO/HQ_DEV",
+        "--permission",
+        "read",
+        "--expires",
+        "2026-07-01T00:00:00.000Z",
+      ],
+      { from: "user" },
+    );
+
+    expect(getCompanyUid).toHaveBeenCalledWith("test-token", "indigo");
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys",
+      method: "POST",
+      body: {
+        companyUid: "cmp_acme",
+        name: "CI key",
+        allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
+        permission: "read",
+        expiresAt: "2026-07-01T00:00:00.000Z",
+      },
+    });
+
+    const printed = logSpy.mock.calls
+      .map((call) => call.map((value) => String(value)).join(" "))
+      .join("\n");
+    expect(printed).toContain("Store this key now");
+    expect(printed.match(/hqk_test_secret_value/g)?.length ?? 0).toBe(1);
+    expect(errSpy).not.toHaveBeenCalled();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq api-keys list", () => {
+  it("renders metadata rows and never prints any key value", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        companyUid: "cmp_acme",
+        apiKeys: [
+          {
+            keyId: "key_123",
+            companyUid: "cmp_acme",
+            name: "CI key",
+            scope: {
+              allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
+              permission: "read",
+            },
+            status: "active",
+            createdAt: "2026-06-19T12:00:00.000Z",
+            lastUsedAt: "2026-06-20T08:00:00.000Z",
+            expiresAt: "2026-07-01T00:00:00.000Z",
+            key: { value: "hqk_should_not_print" },
+          },
+        ],
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["api-keys", "--company", "indigo", "list"],
+      { from: "user" },
+    );
+
+    expect(getCompanyUid).toHaveBeenCalledWith("test-token", "indigo");
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys",
+      query: { companyUid: "cmp_acme" },
+    });
+
+    const printed = logSpy.mock.calls
+      .map((call) => call.map((value) => String(value)).join(" "))
+      .join("\n");
+    expect(printed).toContain("KEY ID");
+    expect(printed).toContain("key_123");
+    expect(printed).toContain("CI key");
+    expect(printed).toContain("HQ_PRO/HQ_PROD, HQ_PRO/HQ_DEV");
+    expect(printed).not.toContain("hqk_should_not_print");
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq api-keys revoke", () => {
+  it("POSTs to the revoke route for the provided key id", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        apiKey: {
+          keyId: "key_123",
+          companyUid: "cmp_acme",
+          name: "CI key",
+          scope: {
+            allowedPrefixes: ["HQ_PRO/HQ_PROD"],
+            permission: "read",
+          },
+          status: "revoked",
+          createdAt: "2026-06-19T12:00:00.000Z",
+          lastUsedAt: null,
+          expiresAt: null,
+        },
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(["api-keys", "revoke", "key_123"], {
+      from: "user",
+    });
+
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys/key_123/revoke",
+      method: "POST",
+    });
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("key_123"));
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});

package/src/commands/api-keys.ts

@@ -0,0 +1,306 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+
+type ApiKeyPermission = "read" | "write" | "admin";
+
+interface ApiKeyMetadata {
+  keyId: string;
+  companyUid: string;
+  name: string;
+  scope: {
+    allowedPrefixes: string[];
+    permission: ApiKeyPermission;
+  };
+  status: string;
+  createdAt: string;
+  lastUsedAt?: string | null;
+  expiresAt?: string | null;
+}
+
+interface CreateApiKeyResponse {
+  apiKey: ApiKeyMetadata;
+  key: {
+    value: string;
+  };
+}
+
+interface ListApiKeysResponse {
+  companyUid: string;
+  apiKeys: ApiKeyMetadata[];
+}
+
+interface RevokeApiKeyResponse {
+  apiKey: ApiKeyMetadata;
+}
+
+interface ApiKeysGroupOptions {
+  company?: string;
+}
+
+interface CreateApiKeyOptions {
+  name: string;
+  scope: string[];
+  permission: string;
+  expires?: string;
+}
+
+function collectRepeatedOption(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+function formatMaybe(value?: string | null): string {
+  return value ?? "-";
+}
+
+function formatPrefixes(prefixes: string[]): string {
+  return prefixes.length > 0 ? prefixes.join(", ") : "-";
+}
+
+function parsePermission(value: string): ApiKeyPermission {
+  if (value === "read" || value === "write" || value === "admin") {
+    return value;
+  }
+  throw new Error(
+    `Invalid permission '${value}'. Use one of: read, write, admin.`,
+  );
+}
+
+function parseExpires(expires?: string): string | undefined {
+  if (expires === undefined) return undefined;
+  if (Number.isNaN(Date.parse(expires))) {
+    throw new Error(
+      `Invalid --expires value '${expires}'. Use an ISO-8601 timestamp.`,
+    );
+  }
+  return expires;
+}
+
+async function readApiError(res: Response, action: string): Promise<string> {
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  const message =
+    typeof body.message === "string"
+      ? body.message
+      : typeof body.error === "string"
+        ? body.error
+        : res.statusText;
+
+  if (res.status === 401) {
+    return "Not authenticated - please run `hq login`";
+  }
+  if (res.status === 403) {
+    return `Not authorized to ${action}`;
+  }
+  if (res.status === 404) {
+    return message || "API key not found";
+  }
+  if (res.status >= 500) {
+    return `Server error: ${message}`;
+  }
+  return message || `Request failed (${res.status})`;
+}
+
+function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
+  const rows = apiKeys.map((apiKey) => ({
+    keyId: apiKey.keyId,
+    name: apiKey.name,
+    permission: apiKey.scope.permission,
+    prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+    status: apiKey.status,
+    lastUsedAt: formatMaybe(apiKey.lastUsedAt),
+    expiresAt: formatMaybe(apiKey.expiresAt),
+  }));
+
+  const keyIdWidth = Math.max(6, ...rows.map((row) => row.keyId.length));
+  const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
+  const permissionWidth = Math.max(
+    10,
+    ...rows.map((row) => row.permission.length),
+  );
+  const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+  const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
+  const lastUsedWidth = Math.max(
+    11,
+    ...rows.map((row) => row.lastUsedAt.length),
+  );
+  const expiresWidth = Math.max(
+    10,
+    ...rows.map((row) => row.expiresAt.length),
+  );
+
+  const header = [
+    "KEY ID".padEnd(keyIdWidth),
+    "NAME".padEnd(nameWidth),
+    "PERMISSION".padEnd(permissionWidth),
+    "PREFIXES".padEnd(prefixesWidth),
+    "STATUS".padEnd(statusWidth),
+    "LAST USED".padEnd(lastUsedWidth),
+    "EXPIRES".padEnd(expiresWidth),
+  ].join("  ");
+  console.log(chalk.bold(header));
+
+  for (const row of rows) {
+    console.log(
+      [
+        row.keyId.padEnd(keyIdWidth),
+        row.name.padEnd(nameWidth),
+        row.permission.padEnd(permissionWidth),
+        row.prefixes.padEnd(prefixesWidth),
+        row.status.padEnd(statusWidth),
+        row.lastUsedAt.padEnd(lastUsedWidth),
+        row.expiresAt.padEnd(expiresWidth),
+      ].join("  "),
+    );
+  }
+}
+
+export function registerApiKeysCommand(program: Command): Command {
+  const apiKeys = program
+    .command("api-keys")
+    .description("Manage vault API keys for CI and automation")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  apiKeys
+    .command("create")
+    .description("Create a new API key")
+    .requiredOption("--name <label>", "Human-readable label for the API key")
+    .option(
+      "--scope <prefix>",
+      "Allowed prefix (repeatable)",
+      collectRepeatedOption,
+      [],
+    )
+    .option(
+      "--permission <level>",
+      "Permission level: read | write | admin",
+      "read",
+    )
+    .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
+    .action(async (opts: CreateApiKeyOptions) => {
+      try {
+        if (opts.scope.length === 0) {
+          console.error(
+            chalk.red("Error: at least one --scope <prefix> is required."),
+          );
+          process.exit(1);
+        }
+
+        const permission = parsePermission(opts.permission);
+        const expiresAt = parseExpires(opts.expires);
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(
+          token,
+          (apiKeys.opts() as ApiKeysGroupOptions).company,
+        );
+
+        const res = await vaultApiFetch({
+          token,
+          path: "/v1/api-keys",
+          method: "POST",
+          body: {
+            companyUid,
+            name: opts.name,
+            allowedPrefixes: opts.scope,
+            permission,
+            ...(expiresAt ? { expiresAt } : {}),
+          },
+        });
+
+        if (!res.ok) {
+          throw new Error(await readApiError(res, "create API keys"));
+        }
+
+        const data = (await res.json()) as CreateApiKeyResponse;
+        console.log(chalk.green("API key created."));
+        console.log(
+          chalk.yellow("Store this key now - it won't be shown again:"),
+        );
+        console.log(`\n  ${data.key.value}\n`);
+        console.log(chalk.bold("Metadata"));
+        console.log(`  Key ID: ${data.apiKey.keyId}`);
+        console.log(`  Name: ${data.apiKey.name}`);
+        console.log(`  Company: ${data.apiKey.companyUid}`);
+        console.log(`  Permission: ${data.apiKey.scope.permission}`);
+        console.log(
+          `  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`,
+        );
+        console.log(`  Status: ${data.apiKey.status}`);
+        console.log(`  Created: ${data.apiKey.createdAt}`);
+        console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
+        console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  apiKeys
+    .command("list")
+    .description("List API keys for a company")
+    .action(async () => {
+      try {
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(
+          token,
+          (apiKeys.opts() as ApiKeysGroupOptions).company,
+        );
+
+        const res = await vaultApiFetch({
+          token,
+          path: "/v1/api-keys",
+          query: { companyUid },
+        });
+
+        if (!res.ok) {
+          throw new Error(await readApiError(res, "list API keys"));
+        }
+
+        const data = (await res.json()) as ListApiKeysResponse;
+        if (data.apiKeys.length === 0) {
+          console.log(chalk.dim("No API keys found."));
+          return;
+        }
+
+        renderApiKeysTable(data.apiKeys);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  apiKeys
+    .command("revoke <keyId>")
+    .description("Revoke an API key")
+    .action(async (keyId: string) => {
+      try {
+        const token = await ensureCognitoToken();
+        const res = await vaultApiFetch({
+          token,
+          path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,
+          method: "POST",
+        });
+
+        if (!res.ok) {
+          throw new Error(await readApiError(res, "revoke this API key"));
+        }
+
+        const data = (await res.json()) as RevokeApiKeyResponse;
+        console.log(chalk.green(`Revoked API key '${data.apiKey.keyId}'`));
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  return apiKeys;
+}

package/src/commands/auth.ts

@@ -4,13 +4,13 @@
  * Subcommands:
  *   hq auth login     — open the Cognito Hosted UI in the browser and cache tokens
  *   hq auth logout    — clear the cached HQ session
- *   hq auth refresh   — refresh the cached Cognito session (non-interactive)
+ *   hq auth refresh   — ensure a valid cached Cognito session (non-interactive)
  *   hq auth status    — show whether a valid session is cached + expiry
  *
  * Sign-up is owned by the onboarding web app at
  * https://onboarding.indigo-hq.com. `hq auth login` signs an existing account
  * into this machine by writing ~/.hq/cognito-tokens.json; once cached, the
- * session is kept fresh by `hq auth refresh` / `hq-auth-refresh` and consumed
+ * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
  */
 
@@ -137,16 +137,16 @@ export function registerAuthCommands(program: Command): void {
   authCmd
     .command("refresh")
     .description(
-      "Refresh the cached Cognito session using the stored refresh token",
+      "Ensure a valid cached Cognito session (refresh only if expiring; no-op if already valid)",
     )
     .action(async () => {
       const result = await refreshCachedSession();
       if (result.refreshed) {
-        console.log(chalk.green("HQ session refreshed"));
+        console.log(chalk.green("HQ session ensured"));
         return;
       }
       console.error(
-        chalk.yellow(`No refresh: ${result.reason ?? "unknown"}`),
+        chalk.yellow(`No valid session: ${result.reason ?? "unknown"}`),
       );
       process.exit(1);
     });

package/src/index.ts

@@ -28,6 +28,7 @@ import { registerPublishCommand } from "./commands/publish.js";
 import { registerCreatorsCommand } from "./commands/creators.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiKeysCommand } from "./commands/api-keys.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
@@ -144,6 +145,9 @@ registerAuthCommands(program);
 // Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
 registerSecretsCommand(program);
 
+// API key management (subcommand group — hq api-keys create|list|revoke)
+registerApiKeysCommand(program);
+
 // Schema-driven dev runner — hq run [options] -- <cmd>
 registerRunCommand(program);
 

package/src/utils/cognito-session.machine.test.ts

@@ -6,7 +6,7 @@
  *     authorizer accepts ID tokens and the agent claims
  *     (custom:entityType/custom:entityUid) ride the ID token only
  *   - never refresh or open a browser — sessions re-mint on demand
- *   - treat `hq auth refresh` as a fresh mint instead of "no cached session"
+ *   - treat `hq auth refresh` as a non-interactive ensure-valid-session call
  */
 
 import { describe, it, expect, beforeEach, vi } from "vitest";
@@ -81,34 +81,29 @@ describe("ensureCognitoToken in machine mode", () => {
 });
 
 describe("refreshCachedSession in machine mode", () => {
-  it("re-mints instead of answering 'no cached session'", async () => {
+  it("ensures a healthy machine session via getValidMachineTokens", async () => {
     mocks.isMachineIdentity.mockReturnValue(true);
-    mocks.mintMachineTokens.mockResolvedValue(MACHINE_TOKENS);
-    mocks.loadCachedTokens.mockReturnValue(null);
+    mocks.getValidMachineTokens.mockResolvedValue(MACHINE_TOKENS);
 
     const result = await refreshCachedSession();
 
     expect(result).toEqual({ refreshed: true });
-    expect(mocks.mintMachineTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.getValidMachineTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.mintMachineTokens).not.toHaveBeenCalled();
     expect(mocks.refreshTokens).not.toHaveBeenCalled();
+    expect(mocks.browserLogin).not.toHaveBeenCalled();
+    expect(mocks.loadCachedTokens).not.toHaveBeenCalled();
   });
 
-  it("surfaces the mint error as the reason on failure", async () => {
+  it("surfaces the machine-session error as the reason on failure", async () => {
     mocks.isMachineIdentity.mockReturnValue(true);
-    mocks.mintMachineTokens.mockRejectedValue(new Error("NotAuthorized"));
+    mocks.getValidMachineTokens.mockRejectedValue(new Error("NotAuthorized"));
 
     const result = await refreshCachedSession();
 
     expect(result.refreshed).toBe(false);
     expect(result.reason).toContain("NotAuthorized");
-  });
-
-  it("keeps the human refresh path unchanged", async () => {
-    mocks.isMachineIdentity.mockReturnValue(false);
-    mocks.loadCachedTokens.mockReturnValue(null);
-
-    const result = await refreshCachedSession();
-
-    expect(result).toEqual({ refreshed: false, reason: "no cached session" });
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+    expect(mocks.browserLogin).not.toHaveBeenCalled();
   });
 });

package/src/utils/cognito-session.refresh.test.ts

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  isMachineIdentity: vi.fn(),
+  getValidMachineTokens: vi.fn(),
+  mintMachineTokens: vi.fn(),
+  loadCachedTokens: vi.fn(),
+  refreshTokens: vi.fn(),
+  browserLogin: vi.fn(),
+  isExpiring: vi.fn(),
+}));
+
+vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@indigoai-us/hq-cloud")>();
+  return { ...actual, ...mocks };
+});
+
+import { refreshCachedSession } from "./cognito-session.js";
+
+const HUMAN_TOKENS = {
+  accessToken: "human-access-token",
+  idToken: "human-id-token",
+  refreshToken: "human-refresh-token",
+  expiresAt: Date.now() + 3600_000,
+  tokenType: "Bearer" as const,
+};
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+describe("refreshCachedSession in human mode", () => {
+  it("returns no cached session without attempting a refresh", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(null);
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: false, reason: "no cached session" });
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+  });
+
+  it("returns success on a healthy cached session without refreshing", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.isExpiring.mockReturnValue(false);
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: true });
+    expect(mocks.isExpiring).toHaveBeenCalledWith(HUMAN_TOKENS, 120);
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+  });
+
+  it("refreshes once when the cached session is expiring", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.isExpiring.mockReturnValue(true);
+    mocks.refreshTokens.mockResolvedValue({
+      ...HUMAN_TOKENS,
+      accessToken: "refreshed-access-token",
+    });
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: true });
+    expect(mocks.refreshTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.refreshTokens).toHaveBeenCalledWith(
+      expect.any(Object),
+      HUMAN_TOKENS.refreshToken,
+    );
+  });
+
+  it("surfaces refresh failures as a non-throwing result", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.isExpiring.mockReturnValue(true);
+    mocks.refreshTokens.mockRejectedValue(new Error("token expired"));
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: false, reason: "token expired" });
+  });
+});

package/src/utils/cognito-session.ts

@@ -32,7 +32,6 @@ import {
   detectHqCoreVersion,
   isMachineIdentity,
   getValidMachineTokens,
-  mintMachineTokens,
   type CognitoAuthConfig,
   type ClientInfo,
   type VaultServiceConfig,
@@ -399,20 +398,22 @@ export function buildVaultConfig(authToken: string): VaultServiceConfig {
 }
 
 /**
- * Refresh the cached Cognito session once and return the result. Used by
- * `hq auth refresh` and the `hq-auth-refresh` bin. Never opens a browser —
- * if no cached tokens exist or the refresh fails, returns `refreshed: false`
- * with a reason string so the caller can decide what to do.
+ * Ensure a valid cached Cognito session exists right now, non-interactively,
+ * and return the result. Used by `hq auth refresh` and the `hq-auth-refresh`
+ * bin. `refreshed: true` means a valid session is ensured now from a healthy
+ * cache hit, a token refresh, or a machine-token mint. `refreshed: false`
+ * means no valid session could be ensured non-interactively; the caller gets a
+ * reason string and can decide what to do next. Never opens a browser.
  */
 export async function refreshCachedSession(): Promise<{
   refreshed: boolean;
   reason?: string;
 }> {
-  // Machine identities have no refresh token — a "refresh" is a fresh mint
-  // from the long-lived machine creds.
+  // Machine identities have no refresh token; ensure a valid cached machine
+  // session without forcing a re-mint when the cache is already healthy.
   if (isMachineIdentity()) {
     try {
-      await mintMachineTokens(DEFAULT_COGNITO);
+      await getValidMachineTokens(DEFAULT_COGNITO);
       return { refreshed: true };
     } catch (err) {
       return {
@@ -426,6 +427,11 @@ export async function refreshCachedSession(): Promise<{
   if (!cached) {
     return { refreshed: false, reason: "no cached session" };
   }
+
+  if (!isExpiring(cached, 120)) {
+    return { refreshed: true };
+  }
+
   try {
     await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
     return { refreshed: true };