@tapi-dev/sdk 0.1.36 → 0.1.38

package/README.md

@@ -52,9 +52,10 @@ The current artifact and current release are kept.
 
 Useful commands:
 
-```bash
-tapi init --project brokerage
-tapi link --project brokerage
+```bash
+tapi login
+tapi init --project brokerage
+tapi link --project brokerage
 tapi studio
 tapi service install --channel pilot
 tapi service status
@@ -80,8 +81,8 @@ ServiceMaps and service-run contracts are saved in the bound Tapi server
 project. Runtime SDK calls read the service catalog from that project.
 
 ```bash
-TAPI_API_KEY=tapi_project_key tapi tapp create brokerage --name "Brokerage"
-TAPI_API_KEY=tapi_project_key tapi tapp service add brokerage schwab.place_order \
+tapi tapp create brokerage --name "Brokerage"
+tapi tapp service add brokerage schwab.place_order \
   --service-map sm_123 \
   --entry place_order
 ```
@@ -102,23 +103,23 @@ page that can create or accept a queue id, attach that queue to the Tapp, and
 assign one or more slots on the runner:
 
 ```bash
-TAPI_API_KEY=tapi_project_key tapi runner setup \
+tapi runner setup \
   --runner-id john-laptop \
   --project brokerage
 ```
 
 ## Quick Start
 
-Create one TAPI client in server-side app code. Use a developer API key, the
-Tapp id that owns the service call, and optionally the same project id from
-`.tapi/project.json`.
+Create one TAPI client in server-side app code. Use a Firebase ID token for the
+developer identity that owns and pays for the Tapp, the Tapp id that owns the
+service call, and optionally the same project id from `.tapi/project.json`.
 
 ```ts
 import { TapiClient } from "@tapi-dev/sdk";
 
 export const tapi = new TapiClient({
   baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
+  authToken: process.env.TAPI_FIREBASE_ID_TOKEN!,
   tappId: process.env.TAPI_TAPP_ID!,
   projectId: process.env.TAPI_PROJECT_ID!,
 });
@@ -130,7 +131,7 @@ holding a browser open:
 ```ts
 const tapi = new TapiClient({
   baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
+  authToken: process.env.TAPI_FIREBASE_ID_TOKEN!,
   tappId: process.env.TAPI_TAPP_ID!,
   projectId: process.env.TAPI_PROJECT_ID!,
   dev: false,
@@ -144,7 +145,7 @@ production failure:
 ```ts
 const tapi = new TapiClient({
   baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
+  authToken: process.env.TAPI_FIREBASE_ID_TOKEN!,
   tappId: process.env.TAPI_TAPP_ID!,
   projectId: process.env.TAPI_PROJECT_ID!,
   dev: true,
@@ -269,8 +270,8 @@ export default {
 };
 ```
 
-```bash
-TAPI_API_KEY=tapi_project_key tapi triggers sync
+```bash
+tapi triggers sync
 ```
 
 `triggers sync` upserts by trigger name for the current `.tapi/project.json`
@@ -295,14 +296,13 @@ await tapi.triggers.disable("act_123");
 You can inspect the same input/output contract from the CLI:
 
 ```bash
-tapi services describe schwab.place_order \
-  --api-base-url "$TAPI_BASE_URL" \
-  --api-key "$TAPI_API_KEY" \
-  --project "$TAPI_PROJECT_ID"
-```
-
-Do not expose `TAPI_API_KEY` in public browser bundles. Put the SDK behind your
-own backend route, server action, or job worker when using secret API keys.
+tapi services describe schwab.place_order \
+  --api-base-url "$TAPI_BASE_URL" \
+  --project "$TAPI_PROJECT_ID"
+```
+
+Do not expose developer Firebase ID tokens in public browser bundles. Put the
+SDK behind your own backend route, server action, or job worker.
 
 ## Runtime Profiles and Proxies
 
@@ -370,7 +370,7 @@ If your JavaScript runtime does not provide `WebSocket`, pass one:
 ```ts
 const tapi = new TapiClient({
   baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
+  authToken: process.env.TAPI_FIREBASE_ID_TOKEN!,
   tappId: process.env.TAPI_TAPP_ID!,
   webSocket: MyWebSocketImplementation,
 });
@@ -378,17 +378,16 @@ const tapi = new TapiClient({
 
 ## Configuration
 
-```env
+```env
 TAPI_BASE_URL=https://your-tapi-api-host
-TAPI_API_KEY=tapi_project_key
+TAPI_FIREBASE_ID_TOKEN=firebase_id_token_for_the_tapp_owner
 TAPI_TAPP_ID=brokerage
 TAPI_PROJECT_ID=brokerage
 ```
 
 `tappId` is required. Service calls are made for that Tapp, and the developer
-who owns the Tapp pays for the service delivery. `projectId` is optional when
-the API key is already project-scoped. If provided, the SDK sends it as the
-`X-Tapi-Project` header and the server rejects mismatches.
+who owns the Tapp pays for the service delivery. If provided, `projectId` is
+sent as the `X-Tapi-Project` header and the server rejects mismatches.
 
 ## Common Project Setup
 
@@ -406,7 +405,7 @@ import { TapiClient } from "@tapi-dev/sdk";
 
 export const tapi = new TapiClient({
   baseUrl: process.env.TAPI_BASE_URL!,
-  apiKey: process.env.TAPI_API_KEY!,
+  authToken: process.env.TAPI_FIREBASE_ID_TOKEN!,
   tappId: process.env.TAPI_TAPP_ID!,
   projectId: process.env.TAPI_PROJECT_ID!,
 });
@@ -446,10 +445,10 @@ Cloud runs are requested from the SDK, but VM provisioning, service
 installation, worker leases, browser internals, and AWS cleanup stay on the
 Tapi server. The SDK is only the front door.
 
-Keep this code server-side. Do not put `TAPI_API_KEY` in a browser bundle and
-do not wire AWS or Stripe from the developer's app. The app sends its own user
-identity to Tapi, and Tapi handles prepaid Stripe checkout, credit accounting,
-AWS worker provisioning, and cleanup.
+Keep this code server-side. Do not put developer Firebase ID tokens in a
+browser bundle and do not wire AWS or Stripe from the developer's app. The app
+sends its own user identity to Tapi, and Tapi handles prepaid Stripe checkout,
+credit accounting, AWS worker provisioning, and cleanup.
 
 The minimum developer flow is:
 
@@ -523,7 +522,7 @@ low, `runCloudBatch` converts the server's HTTP `402` into a normal
 `availableBalanceCents`, and `requiredBalanceCents`. That keeps the button
 handler simple.
 
-Credits are scoped under the Tapi API key owner, Tapp id, and
+Credits are scoped under the authenticated Firebase owner, Tapp id, and
 `user.externalUserId`. Use the same `externalUserId` for quote, balance,
 checkout, and run calls. If you omit `externalUserId` but provide `email`, Tapi
 uses the normalized email as the external user id.

package/dist/cli.d.ts

@@ -71,7 +71,7 @@ export interface StudioCliOptions {
 }
 export interface RunnerSetupCliOptions {
     apiBaseUrl: string;
-    apiKey: string;
+    authToken?: string;
     projectId: string;
     runnerId: string;
     port: number;

package/dist/cli.js

@@ -117,6 +117,50 @@ async function withCliSpinner(message, work) {
         throw error;
     }
 }
+async function withSdkAuth(options) {
+    if (options.authToken?.trim()) {
+        return { ...options, authToken: options.authToken.trim() };
+    }
+    const envAuthToken = envString("TAPI_FIREBASE_ID_TOKEN");
+    if (envAuthToken) {
+        return { ...options, authToken: envAuthToken };
+    }
+    const credentials = await requireSdkFirebaseCredentials();
+    return { ...options, authToken: credentials.idToken };
+}
+async function requireSdkFirebaseCredentials() {
+    const credentials = await refreshCachedFirebaseCredentials();
+    if (!credentials) {
+        throw new Error(`Tapi sign-in is required. Run \`tapi login\`, then retry.`);
+    }
+    await writeStudioAuthCache(credentials);
+    return credentials;
+}
+async function runLogin() {
+    try {
+        const credentials = await withCliSpinner("Signing in to Tapi", () => authenticateSdkUser());
+        console.log(`Signed in to Tapi as ${credentials.uid}.`);
+        return 0;
+    }
+    catch (error) {
+        console.error(formatError(error));
+        return 1;
+    }
+}
+async function authenticateSdkUser() {
+    const cached = await refreshCachedFirebaseCredentials();
+    if (cached) {
+        await writeStudioAuthCache(cached);
+        return cached;
+    }
+    const browserAuth = await browserGoogleSignIn();
+    if (!browserAuth.idToken) {
+        throw new Error(browserAuth.error || browserAuth.detail || "Browser sign-in did not return a Google ID token.");
+    }
+    const credentials = await exchangeGoogleToFirebase(browserAuth.idToken, browserAuth.accessToken);
+    await writeStudioAuthCache(credentials);
+    return credentials;
+}
 export async function runCli(argv = process.argv.slice(2)) {
     const [command, subcommand, ...rest] = argv;
     if (!command || command === "help" || command === "--help" || command === "-h") {
@@ -127,6 +171,18 @@ export async function runCli(argv = process.argv.slice(2)) {
         console.log(sdkVersion);
         return 0;
     }
+    if (command === "login") {
+        if (hasHelpFlag([subcommand, ...rest])) {
+            printLoginHelp();
+            return 0;
+        }
+        if (subcommand) {
+            console.error(`Unexpected login argument: ${subcommand}`);
+            printLoginHelp();
+            return 1;
+        }
+        return runLogin();
+    }
     if (command === "doctor") {
         if (hasHelpFlag([subcommand, ...rest])) {
             printStudioHelp();
@@ -430,7 +486,6 @@ function parseServiceOptions(args) {
     let operation = "";
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
@@ -448,14 +503,6 @@ function parseServiceOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -476,9 +523,6 @@ function parseServiceOptions(args) {
     if (!operation) {
         throw new Error("services describe requires a service run like schwab.place_order.");
     }
-    if (!apiKey) {
-        throw new Error("services describe requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("services describe requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
     }
@@ -486,7 +530,6 @@ function parseServiceOptions(args) {
         operation,
         options: {
             apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-            apiKey,
             projectId,
         },
     };
@@ -494,11 +537,12 @@ function parseServiceOptions(args) {
 async function describeServiceOperation(args) {
     try {
         const { operation, options } = parseServiceOptions(args);
+        const authenticated = await withSdkAuth(options);
         const client = new TapiClient({
-            baseUrl: options.apiBaseUrl,
-            apiKey: options.apiKey,
-            tappId: options.projectId,
-            projectId: options.projectId,
+            baseUrl: authenticated.apiBaseUrl,
+            authToken: authenticated.authToken,
+            tappId: authenticated.projectId,
+            projectId: authenticated.projectId,
         });
         const description = await withCliSpinner(`Fetching Tapi service-run contract for ${operation}`, () => client.services.describe(operation));
         console.log(JSON.stringify(description, null, 2));
@@ -512,7 +556,6 @@ async function describeServiceOperation(args) {
 function parseApiWorkspaceOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let catalogPath = workspace?.config.services?.catalog || ".tapi/services/catalog.json";
     for (let index = 0; index < args.length; index += 1) {
@@ -531,14 +574,6 @@ function parseApiWorkspaceOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -557,23 +592,19 @@ function parseApiWorkspaceOptions(args) {
         }
         throw new Error(`Unknown services option: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("services command requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("services command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
     }
     const root = workspace?.root || process.cwd();
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         projectId,
         catalogPath: resolve(root, catalogPath),
     };
 }
 async function syncServiceCatalog(args) {
     try {
-        const options = parseApiWorkspaceOptions(args);
+        const options = await withSdkAuth(parseApiWorkspaceOptions(args));
         const catalog = await withCliSpinner("Fetching Tapi service-run catalog", () => fetchApiCatalog(options));
         await writeJsonFile(options.catalogPath, catalog);
         console.log(`Synced Tapi service-run catalog: ${options.catalogPath}`);
@@ -587,7 +618,6 @@ async function syncServiceCatalog(args) {
 function parseTappServiceAddOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let tappId = "";
     let serviceCall = "";
     let serviceMapId = "";
@@ -609,14 +639,6 @@ function parseTappServiceAddOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--service-map") {
             serviceMapId = requireOptionValue(args, ++index, "--service-map");
             continue;
@@ -654,9 +676,6 @@ function parseTappServiceAddOptions(args) {
         }
         throw new Error(`Unexpected tapp service add argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("tapp service add requires --api-key or TAPI_API_KEY.");
-    }
     if (!tappId) {
         throw new Error("tapp service add requires a Tapp id.");
     }
@@ -671,7 +690,6 @@ function parseTappServiceAddOptions(args) {
     }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         tappId,
         serviceCall,
         serviceMapId,
@@ -682,7 +700,6 @@ function parseTappServiceAddOptions(args) {
 function parseTappCreateOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let tappId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let name = "";
     for (let index = 0; index < args.length; index += 1) {
@@ -701,14 +718,6 @@ function parseTappCreateOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--tapp-id" || arg === "--project") {
             tappId = normalizeProjectValue(requireOptionValue(args, ++index, arg), "tapp");
             continue;
@@ -741,9 +750,6 @@ function parseTappCreateOptions(args) {
         }
         throw new Error(`Unexpected tapp create argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("tapp create requires --api-key or TAPI_API_KEY.");
-    }
     if (!tappId) {
         throw new Error("tapp create requires a Tapp id or name.");
     }
@@ -752,14 +758,13 @@ function parseTappCreateOptions(args) {
     }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         tappId,
         name,
     };
 }
 async function createTapp(args) {
     try {
-        const options = parseTappCreateOptions(args);
+        const options = await withSdkAuth(parseTappCreateOptions(args));
         const tapp = await withCliSpinner(`Creating Tapi Tapp ${options.tappId}`, () => postTappCreate(options));
         console.log(JSON.stringify(tapp, null, 2));
         return 0;
@@ -772,11 +777,7 @@ async function createTapp(args) {
 async function postTappCreate(options, fetchImpl = fetch) {
     const response = await fetchImpl(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps`, {
         method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "X-API-Key": options.apiKey,
-            "X-Tapi-Project": options.tappId,
-        },
+        headers: sdkJsonHeaders(options.authToken, options.tappId),
         body: JSON.stringify({
             tappId: options.tappId,
             name: options.name,
@@ -791,7 +792,7 @@ async function postTappCreate(options, fetchImpl = fetch) {
 }
 async function addTappService(args) {
     try {
-        const options = parseTappServiceAddOptions(args);
+        const options = await withSdkAuth(parseTappServiceAddOptions(args));
         const operation = await withCliSpinner(`Adding Tapi service ${options.serviceCall} to ${options.tappId}`, () => postTappServiceAdd(options));
         console.log(JSON.stringify(operation, null, 2));
         return 0;
@@ -804,11 +805,7 @@ async function addTappService(args) {
 async function postTappServiceAdd(options) {
     const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps/${encodeURIComponent(options.tappId)}/services/${encodeURIComponent(options.serviceCall)}`, {
         method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "X-API-Key": options.apiKey,
-            "X-Tapi-Project": options.tappId,
-        },
+        headers: sdkJsonHeaders(options.authToken, options.tappId),
         body: JSON.stringify({
             serviceMapId: options.serviceMapId,
             entry: options.entry,
@@ -825,7 +822,6 @@ async function postTappServiceAdd(options) {
 function parseQueueCreateOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let displayName = "";
     let maxSlots = 8;
@@ -845,14 +841,6 @@ function parseQueueCreateOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -878,12 +866,8 @@ function parseQueueCreateOptions(args) {
         }
         throw new Error(`Unexpected queue create argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("queue create requires --api-key or TAPI_API_KEY.");
-    }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         projectId,
         displayName,
         maxSlots,
@@ -892,7 +876,6 @@ function parseQueueCreateOptions(args) {
 function parseTappQueueAddOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let tappId = "";
     let queueId = "";
     for (let index = 0; index < args.length; index += 1) {
@@ -911,14 +894,6 @@ function parseTappQueueAddOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg.startsWith("--")) {
             throw new Error(`Unknown tapp queue add option: ${arg}`);
         }
@@ -932,9 +907,6 @@ function parseTappQueueAddOptions(args) {
         }
         throw new Error(`Unexpected tapp queue add argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("tapp queue add requires --api-key or TAPI_API_KEY.");
-    }
     if (!tappId) {
         throw new Error("tapp queue add requires a Tapp id.");
     }
@@ -943,7 +915,6 @@ function parseTappQueueAddOptions(args) {
     }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         tappId,
         queueId,
     };
@@ -951,7 +922,6 @@ function parseTappQueueAddOptions(args) {
 function parseRunnerSlotSetOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let runnerId = "";
     let slotIndex = 0;
@@ -972,14 +942,6 @@ function parseRunnerSlotSetOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -1005,9 +967,6 @@ function parseRunnerSlotSetOptions(args) {
         }
         throw new Error(`Unexpected runner slot set argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("runner slot set requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("runner slot set requires --project or TAPI_PROJECT_ID.");
     }
@@ -1022,7 +981,6 @@ function parseRunnerSlotSetOptions(args) {
     }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         projectId,
         runnerId,
         slotIndex,
@@ -1031,7 +989,7 @@ function parseRunnerSlotSetOptions(args) {
 }
 async function createQueue(args) {
     try {
-        const options = parseQueueCreateOptions(args);
+        const options = await withSdkAuth(parseQueueCreateOptions(args));
         const queue = await withCliSpinner(`Creating Tapi queue`, () => postQueueCreate(options));
         console.log(JSON.stringify(queue, null, 2));
         return 0;
@@ -1043,7 +1001,7 @@ async function createQueue(args) {
 }
 async function addTappQueue(args) {
     try {
-        const options = parseTappQueueAddOptions(args);
+        const options = await withSdkAuth(parseTappQueueAddOptions(args));
         const result = await withCliSpinner(`Attaching Tapi queue ${options.queueId} to ${options.tappId}`, () => postTappQueueAdd(options));
         console.log(JSON.stringify(result, null, 2));
         return 0;
@@ -1055,7 +1013,7 @@ async function addTappQueue(args) {
 }
 async function setRunnerSlot(args) {
     try {
-        const options = parseRunnerSlotSetOptions(args);
+        const options = await withSdkAuth(parseRunnerSlotSetOptions(args));
         const result = await withCliSpinner(`Assigning runner slot ${options.runnerId}/${options.slotIndex} to queue ${options.queueId}`, () => putRunnerSlot(options));
         console.log(JSON.stringify(result, null, 2));
         return 0;
@@ -1066,13 +1024,7 @@ async function setRunnerSlot(args) {
     }
 }
 async function postQueueCreate(options) {
-    const headers = {
-        "Content-Type": "application/json",
-        "X-API-Key": options.apiKey,
-    };
-    if (options.projectId) {
-        headers["X-Tapi-Project"] = options.projectId;
-    }
+    const headers = sdkJsonHeaders(options.authToken, options.projectId);
     const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/queues`, {
         method: "POST",
         headers,
@@ -1091,11 +1043,7 @@ async function postQueueCreate(options) {
 async function postTappQueueAdd(options) {
     const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps/${encodeURIComponent(options.tappId)}/queues`, {
         method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "X-API-Key": options.apiKey,
-            "X-Tapi-Project": options.tappId,
-        },
+        headers: sdkJsonHeaders(options.authToken, options.tappId),
         body: JSON.stringify({ queueId: options.queueId }),
     });
     const body = await readJsonBody(response);
@@ -1108,11 +1056,7 @@ async function postTappQueueAdd(options) {
 async function putRunnerSlot(options) {
     const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/runners/${encodeURIComponent(options.runnerId)}/slots/${encodeURIComponent(String(options.slotIndex))}`, {
         method: "PUT",
-        headers: {
-            "Content-Type": "application/json",
-            "X-API-Key": options.apiKey,
-            "X-Tapi-Project": options.projectId,
-        },
+        headers: sdkJsonHeaders(options.authToken, options.projectId),
         body: JSON.stringify({ queueId: options.queueId }),
     });
     const body = await readJsonBody(response);
@@ -1125,7 +1069,6 @@ async function putRunnerSlot(options) {
 export function parseRunnerSetupOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let runnerId = envString("TAPI_RUNNER_ID") || "";
     let port = Number(envString("TAPI_RUNNER_SETUP_PORT") || "17687");
@@ -1146,14 +1089,6 @@ export function parseRunnerSetupOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -1191,9 +1126,6 @@ export function parseRunnerSetupOptions(args) {
         }
         throw new Error(`Unexpected runner setup argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("runner setup requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("runner setup requires --project or TAPI_PROJECT_ID.");
     }
@@ -1205,7 +1137,6 @@ export function parseRunnerSetupOptions(args) {
     }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         projectId,
         runnerId,
         port,
@@ -1214,7 +1145,7 @@ export function parseRunnerSetupOptions(args) {
 }
 async function runRunnerSetup(args) {
     try {
-        const options = parseRunnerSetupOptions(args);
+        const options = await withSdkAuth(parseRunnerSetupOptions(args));
         const handle = await startRunnerSetupServer(options);
         if (options.openBrowser) {
             openUrlInBrowser(handle.url);
@@ -1252,7 +1183,7 @@ export async function executeRunnerSetupAction(options, action, fetchImpl = fetc
     if (!queueId) {
         queue = await sdkJsonRequest(fetchImpl, `${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/queues`, {
             method: "POST",
-            headers: sdkJsonHeaders(options.apiKey, options.projectId),
+            headers: sdkJsonHeaders(options.authToken, options.projectId),
             body: JSON.stringify({
                 displayName: String(action.displayName || `${options.projectId} queue`).trim(),
                 maxSlots,
@@ -1265,7 +1196,7 @@ export async function executeRunnerSetupAction(options, action, fetchImpl = fetc
     }
     const attachment = await sdkJsonRequest(fetchImpl, `${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/tapps/${encodeURIComponent(options.projectId)}/queues`, {
         method: "POST",
-        headers: sdkJsonHeaders(options.apiKey, options.projectId),
+        headers: sdkJsonHeaders(options.authToken, options.projectId),
         body: JSON.stringify({ queueId }),
     });
     const slots = [];
@@ -1273,7 +1204,7 @@ export async function executeRunnerSetupAction(options, action, fetchImpl = fetc
         const slotIndex = slotStart + offset;
         slots.push(await sdkJsonRequest(fetchImpl, `${options.apiBaseUrl.replace(/\/+$/, "")}/api/sdk/v1/runners/${encodeURIComponent(options.runnerId)}/slots/${encodeURIComponent(String(slotIndex))}`, {
             method: "PUT",
-            headers: sdkJsonHeaders(options.apiKey, options.projectId),
+            headers: sdkJsonHeaders(options.authToken, options.projectId),
             body: JSON.stringify({ queueId }),
         }));
     }
@@ -1416,12 +1347,22 @@ async function sdkJsonRequest(fetchImpl, url, init) {
     }
     return body ?? {};
 }
-function sdkJsonHeaders(apiKey, projectId) {
-    return {
+function sdkJsonHeaders(authToken, projectId) {
+    const headers = {
         "Content-Type": "application/json",
-        "X-API-Key": apiKey,
-        "X-Tapi-Project": projectId,
+        Authorization: `Bearer ${requireSdkAuthToken(authToken)}`,
     };
+    if (projectId) {
+        headers["X-Tapi-Project"] = projectId;
+    }
+    return headers;
+}
+function requireSdkAuthToken(authToken) {
+    const normalized = String(authToken || "").trim();
+    if (!normalized) {
+        throw new Error("Tapi sign-in is required. Run `tapi login`, then retry.");
+    }
+    return normalized;
 }
 function coercePositiveInteger(value, fallback, label) {
     const text = value === undefined || value === null || value === "" ? String(fallback) : String(value);
@@ -1444,7 +1385,6 @@ function parseNonNegativeInteger(value, label) {
 function parseTriggerSyncOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let configPath = "";
     const root = workspace?.root || process.cwd();
@@ -1464,14 +1404,6 @@ function parseTriggerSyncOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -1490,29 +1422,25 @@ function parseTriggerSyncOptions(args) {
         }
         throw new Error(`Unknown triggers option: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("triggers sync requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("triggers sync requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
     }
     return {
         apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-        apiKey,
         projectId,
         configPath: configPath ? resolve(root, configPath) : defaultTriggerConfigPath(root),
     };
 }
 async function syncServiceTriggers(args) {
     try {
-        const options = parseTriggerSyncOptions(args);
+        const options = await withSdkAuth(parseTriggerSyncOptions(args));
         const triggers = await readServiceTriggerConfig(options.configPath);
         if (triggers.length === 0) {
             throw new Error(`No Tapi service triggers found in ${options.configPath}.`);
         }
         const client = new TapiClient({
             baseUrl: options.apiBaseUrl,
-            apiKey: options.apiKey,
+            authToken: options.authToken,
             tappId: options.projectId,
             projectId: options.projectId,
         });
@@ -1532,7 +1460,6 @@ async function syncServiceTriggers(args) {
 function parseSessionsOptions(args) {
     const workspace = loadWorkspace();
     let apiBaseUrl = envString("TAPI_BASE_URL") || workspace?.apiBaseUrl || DEFAULT_STUDIO_API_BASE_URL;
-    let apiKey = envString("TAPI_API_KEY") || "";
     let projectId = envString("TAPI_PROJECT_ID") || workspace?.projectId || "";
     let site = "";
     let sessionId = "";
@@ -1554,14 +1481,6 @@ function parseSessionsOptions(args) {
             apiBaseUrl = arg.slice("--server=".length);
             continue;
         }
-        if (arg === "--api-key") {
-            apiKey = requireOptionValue(args, ++index, "--api-key");
-            continue;
-        }
-        if (arg.startsWith("--api-key=")) {
-            apiKey = arg.slice("--api-key=".length);
-            continue;
-        }
         if (arg === "--project") {
             projectId = normalizeProjectValue(requireOptionValue(args, ++index, "--project"), "project");
             continue;
@@ -1596,9 +1515,6 @@ function parseSessionsOptions(args) {
         }
         throw new Error(`Unexpected sessions argument: ${arg}`);
     }
-    if (!apiKey) {
-        throw new Error("sessions command requires --api-key or TAPI_API_KEY.");
-    }
     if (!projectId) {
         throw new Error("sessions command requires --project, TAPI_PROJECT_ID, or .tapi/project.json.");
     }
@@ -1606,7 +1522,6 @@ function parseSessionsOptions(args) {
         sessionId,
         options: {
             apiBaseUrl: normalizeHttpUrl(apiBaseUrl, "Tapi API base URL"),
-            apiKey,
             projectId,
             site: site || undefined,
             json,
@@ -1617,18 +1532,19 @@ function parseSessionsOptions(args) {
 async function listDevSessions(args) {
     try {
         const { options } = parseSessionsOptions(args);
-        const sessions = await fetchDevSessions(options);
-        if (options.json) {
+        const authenticated = await withSdkAuth(options);
+        const sessions = await fetchDevSessions(authenticated);
+        if (authenticated.json) {
             console.log(JSON.stringify(sessions, null, 2));
             return 0;
         }
         const rows = flattenDevSessions(sessions);
         if (rows.length === 0) {
-            console.log(`No Tapi dev sessions found for project ${sessions.projectId || options.projectId}.`);
+            console.log(`No Tapi dev sessions found for project ${sessions.projectId || authenticated.projectId}.`);
             return 0;
         }
-        if (!options.noInteractive && process.stdin.isTTY && process.stdout.isTTY && rows.some((session) => session.openable)) {
-            return await runSessionsPicker(sessions, options);
+        if (!authenticated.noInteractive && process.stdin.isTTY && process.stdout.isTTY && rows.some((session) => session.openable)) {
+            return await runSessionsPicker(sessions, authenticated);
         }
         console.log(renderDevSessions(sessions));
         const openable = rows.find((session) => session.openable);
@@ -1645,15 +1561,16 @@ async function listDevSessions(args) {
 async function openDevSession(args) {
     try {
         const { sessionId, options } = parseSessionsOptions(args);
+        const authenticated = await withSdkAuth(options);
         if (!sessionId) {
             throw new Error("sessions open requires a session id.");
         }
-        const sessions = await fetchDevSessions(options);
+        const sessions = await fetchDevSessions(authenticated);
         const session = findDevSession(sessions, sessionId);
         if (!session) {
             throw new Error(`Tapi session not found: ${sessionId}`);
         }
-        return await openDevSessionInStudio(session, options);
+        return await openDevSessionInStudio(session, authenticated);
     }
     catch (error) {
         console.error(formatError(error));
@@ -1663,7 +1580,7 @@ async function openDevSession(args) {
 async function fetchDevSessions(options) {
     const client = new TapiClient({
         baseUrl: options.apiBaseUrl,
-        apiKey: options.apiKey,
+        authToken: options.authToken,
         tappId: options.projectId,
         projectId: options.projectId,
     });
@@ -2103,7 +2020,7 @@ function rejectNonPolicyTriggerRuntimeOwner(runtime, fieldName) {
 async function fetchApiCatalog(options) {
     const client = new TapiClient({
         baseUrl: options.apiBaseUrl,
-        apiKey: options.apiKey,
+        authToken: options.authToken,
         tappId: options.projectId,
         projectId: options.projectId,
     });
@@ -4508,8 +4425,9 @@ function readSdkVersion() {
 function printHelp() {
     console.log(`Tapi CLI
 
-Usage:
-  tapi init --project PROJECT
+Usage:
+  tapi login
+  tapi init --project PROJECT
   tapi link --project PROJECT
   tapi studio install [--channel pilot] [--api-base-url URL]
   tapi studio
@@ -4528,8 +4446,9 @@ Usage:
   tapi service status
   tapi doctor
 
-Commands:
-  init            Create .tapi/project.json for this repo
+Commands:
+  login           Sign in with Firebase credentials for SDK commands
+  init            Create .tapi/project.json for this repo
   link            Rebind this repo to an existing Tapi project
   studio install  Download, verify, and run the Tapi Studio installer
   studio          Open Tapi Studio for this repo
@@ -4551,18 +4470,26 @@ Commands:
   doctor          Alias for studio doctor
 `);
 }
+function printLoginHelp() {
+    console.log(`Tapi login
+
+Usage:
+  tapi login
+
+Signs in with the browser and caches Firebase credentials for SDK commands.
+`);
+}
 function printTappHelp() {
     console.log(`Tapi Tapp commands
 
 Usage:
-  tapi tapp create <tapp> [--name NAME] [--api-base-url URL] [--api-key KEY]
-  tapi tapp service add <tapp> <service.call> --service-map ID --entry ENTRY [--api-base-url URL] [--api-key KEY]
-  tapi tapp queue add <tapp> <queue-id> [--api-base-url URL] [--api-key KEY]
+  tapi tapp create <tapp> [--name NAME] [--api-base-url URL]
+  tapi tapp service add <tapp> <service.call> --service-map ID --entry ENTRY [--api-base-url URL]
+  tapi tapp queue add <tapp> <queue-id> [--api-base-url URL]
 
 Options:
   --api-base-url <url>     Tapi API base URL
   --server <url>           Alias for --api-base-url
-  --api-key <key>          Tapi API key; defaults to TAPI_API_KEY
   --tapp-id <id>           Explicit Tapp id for tapp create
   --name <name>            Display name for tapp create
   --service-map <id>       Backing ServiceMap id
@@ -4574,12 +4501,11 @@ function printQueueHelp() {
     console.log(`Tapi queue commands
 
 Usage:
-  tapi queue create [display-name] [--max-slots N] [--project TAPP] [--api-base-url URL] [--api-key KEY]
+  tapi queue create [display-name] [--max-slots N] [--project TAPP] [--api-base-url URL]
 
 Options:
   --api-base-url <url>  Tapi API base URL
   --server <url>        Alias for --api-base-url
-  --api-key <key>       Tapi API key; defaults to TAPI_API_KEY
   --project <id>        Optional project scope for the queue request
   --max-slots <n>       Maximum runner slots this queue may use
 `);
@@ -4588,13 +4514,12 @@ function printRunnerHelp() {
     console.log(`Tapi runner commands
 
 Usage:
-  tapi runner setup --runner-id RUNNER --project TAPP [--port PORT] [--no-open] [--api-base-url URL] [--api-key KEY]
-  tapi runner slot set <runner-id> <slot-index> <queue-id> [--project TAPP] [--api-base-url URL] [--api-key KEY]
+  tapi runner setup --runner-id RUNNER --project TAPP [--port PORT] [--no-open] [--api-base-url URL]
+  tapi runner slot set <runner-id> <slot-index> <queue-id> [--project TAPP] [--api-base-url URL]
 
 Options:
   --api-base-url <url>  Tapi API base URL
   --server <url>        Alias for --api-base-url
-  --api-key <key>       Tapi API key; defaults to TAPI_API_KEY
   --project <id>        Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
   --runner-id <id>      Runner id for setup; defaults to TAPI_RUNNER_ID
   --port <n>            Local setup UI port; defaults to 17687
@@ -4604,16 +4529,15 @@ Options:
 function printSessionsHelp() {
     console.log(`Tapi dev session commands
 
-Usage:
-  tapi sessions [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-  tapi sessions list [--json] [--site SITE]
-  tapi sessions open <session-id> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Options:
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+Usage:
+  tapi sessions [--api-base-url URL] [--project PROJECT]
+  tapi sessions list [--json] [--site SITE]
+  tapi sessions open <session-id> [--api-base-url URL] [--project PROJECT]
+
+Options:
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
   --site <name>          Limit sessions to one sitemap/site
   --json                 Print raw grouped session JSON
   --no-interactive       Print the grouped list without the arrow-key picker
@@ -4622,30 +4546,28 @@ Options:
 function printServicesHelp() {
     console.log(`Tapi ServiceMap service-run commands
 
-Usage:
-  tapi services describe <servicemap.run> [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-  tapi services sync [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Options:
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+Usage:
+  tapi services describe <servicemap.run> [--api-base-url URL] [--project PROJECT]
+  tapi services sync [--api-base-url URL] [--project PROJECT]
+
+Options:
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
   --catalog <path>       Catalog JSON output path
 `);
 }
 function printTriggersHelp() {
     console.log(`Tapi service trigger commands
 
-Usage:
-  tapi triggers sync [--config FILE] [--api-base-url URL] [--api-key KEY] [--project PROJECT]
-
-Options:
-  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
-  --api-base-url <url>   Tapi API base URL
-  --server <url>         Alias for --api-base-url
-  --api-key <key>        Tapi API key; defaults to TAPI_API_KEY
-  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
+Usage:
+  tapi triggers sync [--config FILE] [--api-base-url URL] [--project PROJECT]
+
+Options:
+  --config <path>        Trigger config path; defaults to tapi.config.ts/js/json in the workspace root
+  --api-base-url <url>   Tapi API base URL
+  --server <url>         Alias for --api-base-url
+  --project <id>         Tapi project id; defaults to TAPI_PROJECT_ID or .tapi/project.json
 
 Config:
   export default {

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { TapiClientOptions } from "./types.js";
 export declare class HttpClient {
     private readonly baseUrl;
-    private readonly apiKey;
+    private readonly authToken;
     private readonly tappId;
     private readonly projectId?;
     private readonly fetchImpl;

package/dist/client.js

@@ -1,13 +1,20 @@
 import { TapiError } from "./errors.js";
 export class HttpClient {
     baseUrl;
-    apiKey;
+    authToken;
     tappId;
     projectId;
     fetchImpl;
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/+$/, "");
-        this.apiKey = options.apiKey;
+        this.authToken = options.authToken.trim();
+        if (!this.authToken) {
+            throw new TapiError("authToken is required", {
+                status: 0,
+                code: "invalid_client_config",
+                details: { field: "authToken" },
+            });
+        }
         this.tappId = options.tappId.trim();
         if (!this.tappId) {
             throw new TapiError("tappId is required", {
@@ -35,7 +42,7 @@ export class HttpClient {
         const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
             method,
             headers: {
-                "X-API-Key": this.apiKey,
+                Authorization: `Bearer ${this.authToken}`,
                 "Content-Type": "application/json",
                 "X-Tapi-Tapp": this.tappId,
                 ...(this.projectId ? { "X-Tapi-Project": this.projectId } : {}),

package/dist/types.d.ts

@@ -2,7 +2,7 @@ import type { LateInput } from "./late-input.js";
 export type RunStatus = "queued" | "running" | "waiting_for_input" | "completed" | "failed" | "cancelled" | "needs_developer_attention";
 export interface TapiClientOptions {
     baseUrl: string;
-    apiKey: string;
+    authToken: string;
     tappId: string;
     projectId?: string;
     dev?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapi-dev/sdk",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",