@cantinasecurity/apex-cli 0.1.13 → 0.1.15

package/.claude/skills/apex-cli/SKILL.md

@@ -13,6 +13,10 @@ This skill is bundled with Apex CLI and can be installed into the current reposi
 
 Use Apex through the MCP server when the `apex-*` tools are available.
 
+For serverless, cron, or other HTTP-only integrations, use the hosted Apex REST API instead of CLI or stdio MCP. Its scan trigger, status, and findings contract is documented at https://ai.cantina.xyz/docs/apex-api.
+
+For on-prem or other non-default Apex hosts, make sure the CLI or MCP server runs with `APEX_BASE_URL` set to the external HTTPS Bedrock origin before auth or provider connection flows.
+
 Recommended workflow:
 
 1. Start with `apex-auth-status`.
@@ -28,6 +32,11 @@ Recommended workflow:
 If the Apex MCP server is not configured, fall back to the local CLI:
 
 - Prefer scripted commands over the interactive shell.
+- Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
+- If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --company <company> --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. Service-key commands never initiate login; the secret is shown once. `list` and `revoke` also require an explicit `--company`.
+- For a headless HTTP adapter, read the service key from a secret-backed environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch MCP from the adapter.
+- Hosted API v1 requires the GitHub repository to be linked to an active Apex workspace. It never creates or mutates workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors.
+- Hosted scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended scan, use a new key.
 - Use `--non-interactive` and `--no-open` for automation-friendly CLI calls.
 - Use `--json` whenever structured output is helpful.
 - `apex credits` reports standard credits plus audit and fix review scan entitlements when Bedrock returns those balances.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Cantina agent plugins for security review workflows.",
-    "version": "0.1.13"
+    "version": "0.1.15"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@cantinasecurity/apex-cli",
-        "version": "0.1.13"
+        "version": "0.1.15"
       },
       "description": "Run Apex security scans and review findings from Claude Code.",
-      "version": "0.1.13",
+      "version": "0.1.15",
       "author": {
         "name": "Cantina",
         "email": "support@cantina.xyz"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Run Apex security scans and review findings from Claude Code.",
   "author": {
     "name": "Cantina",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Run Apex security scans and review findings from Codex.",
   "author": {
     "name": "Cantina",

package/.mcp.claude.json

@@ -5,7 +5,7 @@
       "args": [
         "-y",
         "-p",
-        "@cantinasecurity/apex-cli@0.1.13",
+        "@cantinasecurity/apex-cli@0.1.15",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.13",
+      "@cantinasecurity/apex-cli@0.1.15",
       "apex-mcp"
     ],
     "env": {

package/MARKETPLACE.md

@@ -13,7 +13,7 @@ This package is prepared as both a Claude Code plugin and a Codex plugin. The pu
 The plugin MCP configs launch the pinned npm CLI package with:
 
 ```bash
-npx -y -p @cantinasecurity/apex-cli@0.1.13 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.15 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -74,10 +74,13 @@ pnpm apex
 
 By default, the CLI targets `https://ai.cantina.xyz/`.
 
-Use `APEX_BASE_URL` only when testing against a non-production Apex host:
+Use `APEX_BASE_URL` only when targeting a non-default Apex host. For on-prem deployments,
+set it to the same external HTTPS Bedrock origin configured as `ONPREM_PUBLIC_BASE_URL`;
+browser handoffs such as `apex connect github` and `apex-connect-provider` need that
+public origin for GitHub callback and success redirects.
 
 ```bash
-APEX_BASE_URL=https://preview.cantina.xyz pnpm apex
+APEX_BASE_URL=https://bedrock.customer.example pnpm apex
 ```
 
 ## Interactive Shell
@@ -148,6 +151,9 @@ Supported shell commands:
 - `apex doctor`
 - `apex login`
 - `apex logout`
+- `apex service-key create --company <id-or-handle> --name <name> [--scope <scope[,scope]>] [--expires-at <ISO-8601>] [--json]`
+- `apex service-key list --company <id-or-handle> [--json]`
+- `apex service-key revoke <key-id> --company <id-or-handle> [--json]`
 - `apex setup [all|codex|claude|copilot]`
 - `apex telemetry [status|enable|disable]`
 - `apex update`
@@ -161,6 +167,75 @@ Helpful workspace flags:
 
 `apex credits` shows standard scan credits plus audit and fix review scan entitlements when the server returns them.
 
+## Service Keys And The Hosted API
+
+Use the hosted Apex API for HTTP-only, headless integrations such as serverless functions, cron jobs, and internal audit hubs. Use the CLI or stdio MCP server for local and interactive agent workflows. The full HTTP contract is in the [Apex API documentation](https://ai.cantina.xyz/docs/apex-api).
+
+An organization manager can create a service key with an existing Apex device-login session. Service-key commands never start device login implicitly, so run `apex login` first if needed:
+
+```bash
+apex service-key create \
+  --company acme \
+  --name internal-audit-hub \
+  --scope scans:create,scans:read,findings:read \
+  --expires-at 2027-01-01T00:00:00Z
+```
+
+The secret is returned only by `create` and cannot be retrieved later. Store it directly in a secret manager and do not put it in source control, prompts, chat messages, or logs. `--json` also includes the shown-once secret so it can be captured programmatically; handle that output as a credential.
+
+Service keys are organization-level credentials. Grant only the scopes the integration needs: `scans:create` triggers scans, `scans:read` polls status, and `findings:read` retrieves findings. Omit `--scope` to grant all three scopes. For a P1-only adapter that reads manually started scans, create a read-only key with `--scope scans:read,findings:read`.
+
+A key with `findings:read` can retrieve unpublished draft findings for scans in its organization so an external hub can perform triage. Give the key only to systems that are allowed to handle those drafts.
+
+List metadata or revoke a key without exposing its secret:
+
+```bash
+apex service-key list --company acme
+apex service-key revoke <key-id> --company acme
+```
+
+Service-key management is intentionally available only through the scripted CLI. It is not exposed as an MCP tool or interactive-shell command, which keeps raw secrets out of model tool results and transcripts. The CLI requires an existing device-login bearer session, never initiates login from these commands, and never stores a created service key locally.
+
+Use the service key as a bearer token with the hosted scan lifecycle:
+
+```bash
+curl -X POST https://ai.cantina.xyz/api/apex/v1/scans \
+  -H "Authorization: Bearer $APEX_SERVICE_KEY" \
+  -H "Idempotency-Key: $APEX_IDEMPOTENCY_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "repoUrl": "https://github.com/acme/example.git",
+    "commit": "0123456789abcdef0123456789abcdef01234567",
+    "paths": ["services/payments"]
+  }'
+
+curl \
+  -H "Authorization: Bearer $APEX_SERVICE_KEY" \
+  https://ai.cantina.xyz/api/apex/v1/scans/$SCAN_ID
+
+curl \
+  -H "Authorization: Bearer $APEX_SERVICE_KEY" \
+  https://ai.cantina.xyz/api/apex/v1/scans/$SCAN_ID/findings
+```
+
+In v1, the GitHub repository must already be linked to an active Apex workspace. The hosted API never creates, binds, or mutates workspaces. Apex selects the workspace automatically when exactly one active workspace matches the repository; pass the optional `workspaceId` to disambiguate multiple matches. Zero matches, or multiple matches without a valid `workspaceId`, return HTTP `409`.
+
+The optional `paths` array is a set of best-effort focus hints, not a hard repository boundary. Apex may inspect or report code outside those paths. Version one does not yet provide strict path isolation.
+
+Every trigger request requires an `Idempotency-Key`. Generate one stable key for each intended scan and reuse that same key with the identical request body when retrying after a transport error, timeout, or `5xx`. Idempotency is organization-scoped, so a retry remains safe if the service key is rotated between attempts. A definitive `4xx` response is retained; after correcting its precondition, submit the request with a new key. Use a new key for every genuinely new scan. The trigger returns a `scanId`; poll the scan resource until it reaches a terminal status, then fetch findings. The findings response uses the GitLab SAST JSON shape, including unpublished drafts, finding IDs that remain stable when the same scan is re-fetched, titles, descriptions, severities, and source locations when available.
+
+Example prompt for Claude Code:
+
+> Build an Apex adapter for our serverless audit hub using the hosted HTTP API, not the Apex CLI or MCP server. Assume the GitHub repository is already linked to an active Apex workspace; this API must not create or mutate workspaces. Read `APEX_SERVICE_KEY` from the environment, generate one stable `Idempotency-Key` per intended scan, and reuse it with the identical request body only after a transport error, timeout, or `5xx`; after correcting a definitive `4xx`, use a new key. POST the repository URL and exact commit to `/api/apex/v1/scans`, include `workspaceId` when needed to disambiguate matches, and handle a `409` workspace-resolution response. Treat optional `paths` as non-binding focus hints, not a security boundary. Poll `/api/apex/v1/scans/{scanId}` until terminal, then fetch `/api/apex/v1/scans/{scanId}/findings`. Preserve the raw GitLab SAST payload, including drafts, and deduplicate findings by stable ID. Never print or log the service key.
+
+Example prompt for Codex:
+
+> Add Apex to this headless auditor integration using the hosted REST API. Use bearer auth from `APEX_SERVICE_KEY`; do not shell out to `apex` or start MCP. The GitHub repository must already belong to an active Apex workspace, and the adapter must not create or mutate workspaces. Implement scan trigger, `409` workspace-resolution handling, status polling with bounded backoff, terminal failure handling, and findings retrieval. Send `repoUrl`, `commit`, optional `paths`, and optional `workspaceId`; treat `paths` as non-binding focus hints rather than a hard security boundary. Generate a stable `Idempotency-Key` for each intended scan. Preserve it only for an identical transport/timeout/`5xx` retry; after correcting a definitive `4xx`, submit with a new key. Keep the returned `scanId`, and store the unmodified findings payload, including drafts, alongside normalized findings. Add tests with mocked HTTP responses and ensure credentials are redacted from errors and logs.
+
+For a P1-only integration where scans are started in the Apex UI:
+
+> Given an Apex `scanId`, fetch `/api/apex/v1/scans/{scanId}/findings` with `APEX_SERVICE_KEY`, save the GitLab SAST JSON unchanged, and import each finding once using its stable ID. Do not trigger a new scan and never log the bearer token.
+
 ## Finding Review Feedback
 
 Finding review collaboration now has explicit write commands:
@@ -310,6 +385,8 @@ The MCP server exposes Apex-specific tools for:
 - finding comments and valid/invalid feedback with `apex-finding-comment` and `apex-finding-feedback`
 - Fix PR and current-repository fix review scans with `apex-finding-fix-review`, optionally after `apex-finding-feedback`
 
+The MCP server does not expose service-key creation, listing, or revocation. For HTTP-only serverless and cron integrations, use the [hosted Apex API](https://ai.cantina.xyz/docs/apex-api) directly instead of launching the stdio MCP server.
+
 For repository-scoped operations, pass `cwd` explicitly so the server can resolve the right `.apex/workspace.json` binding and repository roots.
 
 For Codex-style clients, the packaged skill can be installed with `apex setup codex`. For GitHub Copilot CLI, the same skill is installed into `~/.copilot/skills/apex-cli` with `apex setup copilot`. The repo-local source lives at `skills/apex-cli/SKILL.md`.
@@ -347,7 +424,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.13",
+      "cliVersion": "0.1.15",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -378,7 +455,7 @@ The npm package also includes marketplace-ready plugin artifacts:
 - `.claude-plugin/plugin.json` and `.mcp.claude.json` for Claude Code plugin installs
 - `.claude-plugin/marketplace.json` for a Claude marketplace entry backed by the public npm package
 
-These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.13 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
+These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.15 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
 
 The repository also includes `.agents/plugins/marketplace.json` for local Codex marketplace testing from a checkout.
 

package/dist/apex.js

@@ -1,6 +1,6 @@
 import { ApexApiClient, formatApiError } from "./api-client.js";
 import { parseArgs } from "./args.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandServiceKeyCreate, commandServiceKeyList, commandServiceKeyRevoke, commandSetup, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { runMcpServer } from "./mcp.js";
 import { runInteractiveShell } from "./shell.js";
@@ -39,6 +39,20 @@ async function dispatch(parsed) {
         case "logout":
             await commandLogout(client, parsed.flags);
             return;
+        case "service-key":
+            if (parsed.subcommand === "create" && parsed.args.length === 0) {
+                await commandServiceKeyCreate(client, parsed.flags);
+                return;
+            }
+            if (parsed.subcommand === "list" && parsed.args.length === 0) {
+                await commandServiceKeyList(client, parsed.flags);
+                return;
+            }
+            if (parsed.subcommand === "revoke" && parsed.args.length === 1) {
+                await commandServiceKeyRevoke(client, parsed.flags, parsed.args[0] ?? "");
+                return;
+            }
+            throw new Error("Usage: apex service-key <create|list|revoke> [key-id] --company <id-or-handle>");
         case "update":
             await commandUpdate(parsed.flags);
             return;

package/dist/commands.js

@@ -1,5 +1,5 @@
 import { canPromptInteractively, getFlagList, getFlagString, isJsonMode, } from "./args.js";
-import { logout } from "./auth.js";
+import { getMe, logout } from "./auth.js";
 import { ApiError } from "./api-client.js";
 import { openInBrowser } from "./browser.js";
 import { loadConfig, saveConfig } from "./config.js";
@@ -8,6 +8,7 @@ import { prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-s
 import { logLine, printJson, withLoadingIndicator } from "./output.js";
 import { confirm } from "./prompt.js";
 import { cancelScan, fetchScanProgress, fetchWorkspaceScans, findMostRelevantActiveScan, getScanDisplayLabel, getScanDisplayId, getTrackedScanId, isActiveScanStatus, matchesScanId, selectDefaultScanToCancel, } from "./scan.js";
+import { createServiceApiKey, isServiceApiScope, listServiceApiKeys, revokeServiceApiKey, SERVICE_API_SCOPES, } from "./service-keys.js";
 import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, remediateMissingConnections, resolveWorkspaceSelection, resolveWorkspaceSelectionLegacy, resolveWorkspaceAllowingMissingConnections, selectWorkspaceTarget, } from "./session.js";
 import { createWorkspaceBindingFromSummary, fetchCompanyCredits, fetchCompanyWorkspaces, findWorkspaceByRef, } from "./workspaces.js";
 import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
@@ -16,6 +17,7 @@ import { getTelemetryStatus, setTelemetryEnabled, } from "./telemetry.js";
 import { commandUpdate as runCliUpdate } from "./update.js";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { z } from "zod";
 const WORKSPACE_USE_PATTERN = "<workspace-name|workspace-prefix|workspace-id>";
 const WORKSPACE_BINDING_GUIDANCE = "Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const WORKSPACE_SELECTION_GUIDANCE = "Run `apex workspaces` to list available workspace names, prefixes, and IDs, then retry `apex workspace use \"<workspace name>\"`.";
@@ -40,6 +42,17 @@ const FIX_REVIEW_TARGETS = [
     "pull_request",
     "repository_current",
 ];
+const SERVICE_KEY_CREATE_USAGE = "Usage: apex service-key create --company <id-or-handle> --name <name> [--scope <scope[,scope]>] [--expires-at <ISO-8601>] [--json]";
+const SERVICE_KEY_LIST_USAGE = "Usage: apex service-key list --company <id-or-handle> [--json]";
+const SERVICE_KEY_REVOKE_USAGE = "Usage: apex service-key revoke <key-id> --company <id-or-handle> [--json]";
+const SERVICE_KEY_EXPIRATION_SCHEMA = z.string().datetime({ offset: true });
+const SERVICE_KEY_NAME_CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/;
+const SERVICE_KEY_NAME_SCHEMA = z
+    .string()
+    .trim()
+    .min(1)
+    .max(100)
+    .refine((value) => !SERVICE_KEY_NAME_CONTROL_CHARACTER_PATTERN.test(value));
 async function saveCompanyDefault(companyId) {
     const config = await loadConfig();
     if (config.defaultCompanyId !== companyId) {
@@ -52,6 +65,72 @@ async function saveCompanyDefault(companyId) {
 function formatCommandArgument(value) {
     return /\s/.test(value) ? `"${value}"` : value;
 }
+function requireExplicitServiceKeyCompany(flags, usage) {
+    if (!getFlagString(flags, "company")) {
+        throw new Error(`${usage}\nService-key commands require an explicit --company.`);
+    }
+}
+async function requireExistingServiceKeySession(client) {
+    const me = await getMe(client);
+    if (!me) {
+        throw new Error("Service-key commands require an existing Apex session. Run `apex login` first.");
+    }
+    return me;
+}
+function normalizeServiceKeyExpiration(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = SERVICE_KEY_EXPIRATION_SCHEMA.safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`${SERVICE_KEY_CREATE_USAGE}\n--expires-at must be a valid ISO-8601 timestamp with a timezone offset.`);
+    }
+    const timestamp = new Date(parsed.data);
+    if (timestamp.getTime() <= Date.now()) {
+        throw new Error(`${SERVICE_KEY_CREATE_USAGE}\n--expires-at must be in the future.`);
+    }
+    return timestamp.toISOString();
+}
+function normalizeServiceKeyName(value) {
+    const parsed = SERVICE_KEY_NAME_SCHEMA.safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`${SERVICE_KEY_CREATE_USAGE}\n--name must be 1-100 characters and cannot contain control characters.`);
+    }
+    return parsed.data;
+}
+function normalizeServiceKeyScopes(flags) {
+    if (!Object.prototype.hasOwnProperty.call(flags, "scope")) {
+        return undefined;
+    }
+    const rawScopes = flags.scope;
+    if (typeof rawScopes !== "string" || rawScopes.trim().length === 0) {
+        throw new Error(`${SERVICE_KEY_CREATE_USAGE}\n--scope must contain one or more comma-separated scopes.`);
+    }
+    const requestedScopes = rawScopes.split(",").map((scope) => scope.trim());
+    if (requestedScopes.some((scope) => scope.length === 0) ||
+        requestedScopes.some((scope) => !isServiceApiScope(scope))) {
+        throw new Error(`${SERVICE_KEY_CREATE_USAGE}\n--scope must contain only: ${SERVICE_API_SCOPES.join(", ")}.`);
+    }
+    return [...new Set(requestedScopes)];
+}
+function escapeTerminalControlCharacters(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function formatServiceKeyScopes(key) {
+    const scopes = [...new Set(key.scopes.filter(isServiceApiScope))];
+    return scopes.length > 0 ? scopes.join(", ") : "none";
+}
+function formatServiceKeyState(key) {
+    if (key.revokedAt) {
+        return `revoked ${escapeTerminalControlCharacters(key.revokedAt)}`;
+    }
+    if (key.expiresAt && new Date(key.expiresAt).getTime() <= Date.now()) {
+        return `expired ${escapeTerminalControlCharacters(key.expiresAt)}`;
+    }
+    return key.expiresAt
+        ? `expires ${escapeTerminalControlCharacters(key.expiresAt)}`
+        : "does not expire";
+}
 function getSuggestedWorkspaceRef(workspace) {
     return workspace.prefix?.trim().length ? workspace.prefix : workspace.name;
 }
@@ -508,6 +587,93 @@ export async function commandLogout(client, flags) {
         logLine("Logged out", flags);
     }
 }
+export async function commandServiceKeyCreate(client, flags) {
+    requireExplicitServiceKeyCompany(flags, SERVICE_KEY_CREATE_USAGE);
+    const name = normalizeServiceKeyName(getFlagString(flags, "name"));
+    const scopes = normalizeServiceKeyScopes(flags);
+    const expiresAt = normalizeServiceKeyExpiration(getFlagString(flags, "expires-at"));
+    const me = await requireExistingServiceKeySession(client);
+    const company = await chooseCompany(me, flags, null);
+    const response = await withLoadingIndicator("Creating service key...", flags, () => createServiceApiKey(client, company.id, {
+        name,
+        expiresAt,
+        ...(scopes ? { scopes } : {}),
+    }));
+    const payload = {
+        company,
+        key: response.key,
+        secret: response.secret,
+        secretShownOnce: true,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Company: ${escapeTerminalControlCharacters(company.handle ?? company.id)}`, flags);
+    logLine(`Service key: ${escapeTerminalControlCharacters(response.key.name)} (${escapeTerminalControlCharacters(response.key.id)})`, flags);
+    if (response.key.prefix) {
+        logLine(`Prefix: ${escapeTerminalControlCharacters(response.key.prefix)}`, flags);
+    }
+    logLine(`Scopes: ${formatServiceKeyScopes(response.key)}`, flags);
+    if (response.key.expiresAt) {
+        logLine(`Expires: ${escapeTerminalControlCharacters(response.key.expiresAt)}`, flags);
+    }
+    process.stdout.write(`Service key (shown once): ${response.secret}\n`);
+    logLine("Store this service key securely now. Apex cannot show it again.", flags);
+    return payload;
+}
+export async function commandServiceKeyList(client, flags) {
+    requireExplicitServiceKeyCompany(flags, SERVICE_KEY_LIST_USAGE);
+    const me = await requireExistingServiceKeySession(client);
+    const company = await chooseCompany(me, flags, null);
+    const response = await withLoadingIndicator("Loading service keys...", flags, () => listServiceApiKeys(client, company.id));
+    const payload = {
+        company,
+        keys: response.keys,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Company: ${escapeTerminalControlCharacters(company.handle ?? company.id)}`, flags);
+    if (response.keys.length === 0) {
+        logLine("Service keys: none.", flags);
+        return payload;
+    }
+    for (const key of response.keys) {
+        const prefix = key.prefix
+            ? `, ${escapeTerminalControlCharacters(key.prefix)}`
+            : "";
+        logLine(`${escapeTerminalControlCharacters(key.name)} (${escapeTerminalControlCharacters(key.id)}${prefix}, ${formatServiceKeyState(key)})`, flags);
+        logLine(`Scopes: ${formatServiceKeyScopes(key)}`, flags);
+        if (key.lastUsedAt) {
+            logLine(`Last used: ${escapeTerminalControlCharacters(key.lastUsedAt)}`, flags);
+        }
+    }
+    return payload;
+}
+export async function commandServiceKeyRevoke(client, flags, requestedKeyId) {
+    requireExplicitServiceKeyCompany(flags, SERVICE_KEY_REVOKE_USAGE);
+    const keyId = requestedKeyId.trim();
+    if (!keyId) {
+        throw new Error(SERVICE_KEY_REVOKE_USAGE);
+    }
+    const me = await requireExistingServiceKeySession(client);
+    const company = await chooseCompany(me, flags, null);
+    await withLoadingIndicator("Revoking service key...", flags, () => revokeServiceApiKey(client, company.id, keyId));
+    const payload = {
+        company,
+        keyId,
+        revoked: true,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Company: ${escapeTerminalControlCharacters(company.handle ?? company.id)}`, flags);
+    logLine(`Revoked service key: ${escapeTerminalControlCharacters(keyId)}`, flags);
+    return payload;
+}
 export async function commandUpdate(flags) {
     return runCliUpdate(flags);
 }

package/dist/help.js

@@ -20,6 +20,9 @@ export const CLI_HELP_TEXT = `Usage:
   apex doctor                       Validate auth, repos, connections, and workspace binding
   apex login                        Sign in to Apex
   apex logout                       Sign out locally
+  apex service-key create           Create an organization service key (shown once)
+  apex service-key list             List service-key metadata for an organization
+  apex service-key revoke <key-id>  Revoke an organization service key
   apex mcp                          Start the Apex MCP server over stdio
   apex setup [all|codex|claude|copilot]
                                     Configure Apex for Codex, Claude Code, and GitHub Copilot CLI
@@ -31,6 +34,9 @@ export const CLI_HELP_TEXT = `Usage:
 
 Flags:
   --company <id-or-handle>          Choose the Apex company to use
+  --name <name>                     Name a new service key
+  --scope <scope[,scope]>           Limit a service key to scans:create, scans:read, and/or findings:read
+  --expires-at <ISO-8601>           Set an optional service-key expiration time
   --workspace-name <name>           Set the Apex workspace name for this directory
   --scan <scan-id>                  Select a specific scan for status, findings, or export
   --status valid|invalid            Set the finding feedback status explicitly
@@ -67,6 +73,9 @@ Tips:
   audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
   apex workspace use accepts a workspace name, prefix, or ID.
   Finding comments, feedback, and fix review scans use the same Apex login credentials as other CLI commands.
+  Service-key commands require an existing login and --company; run apex login first when needed.
+  Service-key creation also requires --name and reveals the secret only once; omit --scope to grant all hosted API scopes.
+  Service-key management is available only in the scripted CLI, not the interactive shell or MCP server.
   Invalid finding feedback requires --dismissal-reason.
   Fix review scans use saved or supplied Fix PR URLs when present; otherwise they review the current repository when Bedrock has original scan repository context.
   Finding identifiers such as KERN2-25 resolve against the selected scan; pass --scan or use the finding UUID directly when needed.

package/dist/mcp.js

@@ -24,6 +24,8 @@ Notes:
 - Pass cwd explicitly for repository-specific operations.
 - Tool calls are always non-interactive and never auto-open a browser.
 - Finding write tools use the same Apex device-login credentials as read tools.
+- Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into an MCP prompt or tool call.
+- HTTP-only serverless and cron integrations should use the hosted API documented at https://ai.cantina.xyz/docs/apex-api instead of launching this stdio server.
 - Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias. Use mode "pr" for GitHub pull request scans.
 - Doctor reports whether Apex will use remote materialization or a local snapshot upload for each source.`;
 const WORKSPACE_BINDING_ERROR = "This directory is not bound to an Apex workspace yet. Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";

package/dist/service-keys.js

@@ -0,0 +1,52 @@
+export const SERVICE_API_SCOPES = [
+    "scans:create",
+    "scans:read",
+    "findings:read",
+];
+export function isServiceApiScope(value) {
+    return (typeof value === "string" &&
+        SERVICE_API_SCOPES.includes(value));
+}
+function serviceApiKeysPath(companyId) {
+    return `/api/companies/${encodeURIComponent(companyId)}/service-api-keys`;
+}
+function serviceApiKeyMetadata(key) {
+    const scopes = Array.isArray(key.scopes)
+        ? [...new Set(key.scopes.filter(isServiceApiScope))]
+        : [...SERVICE_API_SCOPES];
+    return {
+        id: key.id,
+        name: key.name,
+        ...(key.prefix !== undefined ? { prefix: key.prefix } : {}),
+        scopes,
+        createdAt: key.createdAt,
+        expiresAt: key.expiresAt,
+        ...(key.lastUsedAt !== undefined ? { lastUsedAt: key.lastUsedAt } : {}),
+        ...(key.revokedAt !== undefined ? { revokedAt: key.revokedAt } : {}),
+    };
+}
+export async function createServiceApiKey(client, companyId, input) {
+    const response = await client.request(serviceApiKeysPath(companyId), {
+        method: "POST",
+        json: {
+            name: input.name,
+            ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+            ...(input.scopes ? { scopes: input.scopes } : {}),
+        },
+    });
+    return {
+        key: serviceApiKeyMetadata(response.key),
+        secret: response.secret,
+    };
+}
+export async function listServiceApiKeys(client, companyId) {
+    const response = await client.request(serviceApiKeysPath(companyId));
+    return {
+        keys: response.keys.map(serviceApiKeyMetadata),
+    };
+}
+export async function revokeServiceApiKey(client, companyId, keyId) {
+    await client.request(`${serviceApiKeysPath(companyId)}/${encodeURIComponent(keyId)}`, {
+        method: "DELETE",
+    });
+}

package/dist/telemetry.js

@@ -13,6 +13,7 @@ const KNOWN_CLI_FLAG_NAMES = [
     "company",
     "content",
     "dismissal-reason",
+    "expires-at",
     "fix-pr-url",
     "force",
     "format",
@@ -21,6 +22,7 @@ const KNOWN_CLI_FLAG_NAMES = [
     "label",
     "limit",
     "mode",
+    "name",
     "no-open",
     "non-interactive",
     "output",
@@ -30,6 +32,7 @@ const KNOWN_CLI_FLAG_NAMES = [
     "repo",
     "review-target",
     "scan",
+    "scope",
     "source-mode",
     "status",
     "suggested-severity",
@@ -49,6 +52,7 @@ const KNOWN_CLI_COMMANDS = [
     "mcp",
     "scan",
     "scans",
+    "service-key",
     "setup",
     "status",
     "telemetry",
@@ -173,6 +177,8 @@ function sanitizeCliFlags(flags) {
         noOpen: boolFlag(flags, "no-open"),
         companyProvided: stringFlag(flags, "company") !== null,
         workspaceNameProvided: stringFlag(flags, "workspace-name") !== null,
+        nameProvided: stringFlag(flags, "name") !== null,
+        expiresAtProvided: stringFlag(flags, "expires-at") !== null,
         scanIdProvided: stringFlag(flags, "scan") !== null,
         outputProvided: stringFlag(flags, "output") !== null,
         contentProvided: stringFlag(flags, "content") !== null,
@@ -297,6 +303,8 @@ function safeCliSubcommand(parsed) {
             return safeEnum(subcommand, ["comment", "feedback", "fix-review"]);
         case "setup":
             return safeEnum(subcommand, ["all", "codex", "claude", "copilot"]);
+        case "service-key":
+            return safeEnum(subcommand, ["create", "list", "revoke"]);
         case "telemetry":
             return safeEnum(subcommand, ["status", "enable", "disable"]);
         case "workspace":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -9,8 +9,12 @@ This skill is bundled with Apex CLI and can be installed into Codex with `apex s
 
 Prefer the Apex MCP tools over running `apex` in the shell when the server is available.
 
+For serverless, cron, or other HTTP-only integrations, use the hosted Apex REST API instead of CLI or stdio MCP. Its scan trigger, status, and findings contract is documented at https://ai.cantina.xyz/docs/apex-api.
+
 `apex setup codex` configures the MCP server with client attribution so Apex can distinguish Codex MCP usage from direct CLI usage. Users can inspect or disable anonymous local usage telemetry with `apex telemetry status` and `apex telemetry disable`.
 
+For on-prem or other non-default Apex hosts, make sure the MCP server runs with `APEX_BASE_URL` set to the external HTTPS Bedrock origin before auth or provider connection flows.
+
 Workflow:
 
 1. Start with `apex-auth-status`.
@@ -26,6 +30,11 @@ Workflow:
 Guidelines:
 
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
+- Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
+- If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --company <company> --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. Service-key commands never initiate login; the secret is shown once. `list` and `revoke` also require an explicit `--company`.
+- For a headless HTTP adapter, read the service key from a secret-backed environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch MCP from the adapter.
+- Hosted API v1 requires the GitHub repository to be linked to an active Apex workspace. It never creates or mutates workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors.
+- Hosted scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended scan, use a new key.
 - `apex-credits` reports standard credits plus audit and fix review scan entitlements when Bedrock returns those balances.
 - `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.