@honeyhive/control-plane-sdk 1.1.0 → 1.2.0

package/src/generated/client.ts

@@ -1,5 +1,7 @@
 // AUTO-GENERATED — do not edit manually. Run `pnpm turbo run generate` to regenerate.
 
+import { type Client as OpenapiFetchClient } from 'openapi-fetch';
+
 import { type paths } from './types.js';
 import {
   type ListAlertsRequest,
@@ -35,12 +37,23 @@ import {
 } from './apiTypes.js';
 import { type ClientConfig, type FetchOptions, createApiClient, unwrap } from '../util.js';
 
+/** Every security scheme the API's OpenAPI spec defines. */
+export type SecurityScheme = 'ControlPlaneApiKey';
+
+/**
+ * What `createApiClient` returns: for every security scheme the spec defines,
+ * the openapi-fetch client that carries the credential for it. The hand-written
+ * chassis builds this table, so a scheme added to or removed from the spec
+ * fails to compile there until the table says which client serves it.
+ */
+export type ApiClients = Record<SecurityScheme, OpenapiFetchClient<paths>>;
+
 /** @inline */
 class AlertsNamespace {
-  #client: ReturnType<typeof createApiClient<paths>>;
+  #clients: ApiClients;
 
-  constructor(client: ReturnType<typeof createApiClient<paths>>) {
-    this.#client = client;
+  constructor(clients: ApiClients) {
+    this.#clients = clients;
   }
 
   /**
@@ -52,8 +65,9 @@ class AlertsNamespace {
    */
   public list(request: ListAlertsRequest, options?: FetchOptions): Promise<ListAlertsResponse> {
     const { project_id, page, limit, status, sort_by, sort_order } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.GET('/v1/projects/{project_id}/alerts', {
+      httpClient.GET('/v1/projects/{project_id}/alerts', {
         params: { path: { project_id }, query: { page, limit, status, sort_by, sort_order } },
         ...options,
       }),
@@ -71,8 +85,9 @@ class AlertsNamespace {
    */
   public create(request: CreateAlertRequest, options?: FetchOptions): Promise<CreateAlertResponse> {
     const { project_id, ...body } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.POST('/v1/projects/{project_id}/alerts', {
+      httpClient.POST('/v1/projects/{project_id}/alerts', {
         params: { path: { project_id } },
         body,
         ...options,
@@ -89,8 +104,9 @@ class AlertsNamespace {
    */
   public get(request: GetAlertRequest, options?: FetchOptions): Promise<GetAlertResponse> {
     const { project_id, alert_id } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.GET('/v1/projects/{project_id}/alerts/{alert_id}', {
+      httpClient.GET('/v1/projects/{project_id}/alerts/{alert_id}', {
         params: { path: { project_id, alert_id } },
         ...options,
       }),
@@ -100,10 +116,10 @@ class AlertsNamespace {
 
 /** @inline */
 class WorkspacesNamespace {
-  #client: ReturnType<typeof createApiClient<paths>>;
+  #clients: ApiClients;
 
-  constructor(client: ReturnType<typeof createApiClient<paths>>) {
-    this.#client = client;
+  constructor(clients: ApiClients) {
+    this.#clients = clients;
   }
 
   /**
@@ -140,8 +156,9 @@ class WorkspacesNamespace {
     options?: FetchOptions,
   ): Promise<CreateWorkspaceResponse> {
     const { virtual_dataplane_id, ...body } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.POST('/v1/virtual_dataplanes/{virtual_dataplane_id}/workspaces', {
+      httpClient.POST('/v1/virtual_dataplanes/{virtual_dataplane_id}/workspaces', {
         params: { path: { virtual_dataplane_id } },
         body,
         ...options,
@@ -160,8 +177,9 @@ class WorkspacesNamespace {
    */
   public get(request: GetWorkspaceRequest, options?: FetchOptions): Promise<GetWorkspaceResponse> {
     const { workspace_id } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.GET('/v1/workspaces/{workspace_id}', {
+      httpClient.GET('/v1/workspaces/{workspace_id}', {
         params: { path: { workspace_id } },
         ...options,
       }),
@@ -182,8 +200,9 @@ class WorkspacesNamespace {
     options?: FetchOptions,
   ): Promise<UpdateWorkspaceResponse> {
     const { workspace_id, ...body } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.PUT('/v1/workspaces/{workspace_id}', {
+      httpClient.PUT('/v1/workspaces/{workspace_id}', {
         params: { path: { workspace_id } },
         body,
         ...options,
@@ -213,8 +232,9 @@ class WorkspacesNamespace {
     options?: FetchOptions,
   ): Promise<DeleteWorkspaceResponse> {
     const { workspace_id, dangerously_delete_child_scopes } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.DELETE('/v1/workspaces/{workspace_id}', {
+      httpClient.DELETE('/v1/workspaces/{workspace_id}', {
         params: { path: { workspace_id }, query: { dangerously_delete_child_scopes } },
         ...options,
       }),
@@ -224,10 +244,10 @@ class WorkspacesNamespace {
 
 /** @inline */
 class ProjectsNamespace {
-  #client: ReturnType<typeof createApiClient<paths>>;
+  #clients: ApiClients;
 
-  constructor(client: ReturnType<typeof createApiClient<paths>>) {
-    this.#client = client;
+  constructor(clients: ApiClients) {
+    this.#clients = clients;
   }
 
   /**
@@ -259,8 +279,9 @@ class ProjectsNamespace {
     options?: FetchOptions,
   ): Promise<CreateProjectResponse> {
     const { workspace_id, ...body } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.POST('/v1/workspaces/{workspace_id}/projects', {
+      httpClient.POST('/v1/workspaces/{workspace_id}/projects', {
         params: { path: { workspace_id } },
         body,
         ...options,
@@ -276,11 +297,9 @@ class ProjectsNamespace {
    */
   public get(request: GetProjectRequest, options?: FetchOptions): Promise<GetProjectResponse> {
     const { project_id } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.GET('/v1/projects/{project_id}', {
-        params: { path: { project_id } },
-        ...options,
-      }),
+      httpClient.GET('/v1/projects/{project_id}', { params: { path: { project_id } }, ...options }),
     );
   }
 
@@ -296,8 +315,9 @@ class ProjectsNamespace {
     options?: FetchOptions,
   ): Promise<UpdateProjectResponse> {
     const { project_id, ...body } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.PUT('/v1/projects/{project_id}', {
+      httpClient.PUT('/v1/projects/{project_id}', {
         params: { path: { project_id } },
         body,
         ...options,
@@ -317,8 +337,9 @@ class ProjectsNamespace {
     options?: FetchOptions,
   ): Promise<DeleteProjectResponse> {
     const { project_id } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.DELETE('/v1/projects/{project_id}', {
+      httpClient.DELETE('/v1/projects/{project_id}', {
         params: { path: { project_id } },
         ...options,
       }),
@@ -328,10 +349,10 @@ class ProjectsNamespace {
 
 /** @inline */
 class VirtualDataplanesNamespace {
-  #client: ReturnType<typeof createApiClient<paths>>;
+  #clients: ApiClients;
 
-  constructor(client: ReturnType<typeof createApiClient<paths>>) {
-    this.#client = client;
+  constructor(clients: ApiClients) {
+    this.#clients = clients;
   }
 
   /**
@@ -355,12 +376,11 @@ class VirtualDataplanesNamespace {
    * A cluster admits an organization only if your control plane administrator configured it to,
    * so a `cluster_id` you can read from a sibling virtual data plane is not necessarily one you
    * may place a new virtual data plane on. A cluster that does not admit this organization
-   * returns a 403. When you named the cluster, the fix is a configuration change your
-   * administrator makes. When this endpoint inferred the cluster, send an explicit `cluster_id`
-   * to place the virtual data plane on another cluster.
+   * returns a 404. When this endpoint inferred the cluster, send an explicit `cluster_id` to
+   * place the virtual data plane on another cluster.
    *
    * Deployments differ in who places virtual data planes. Where HoneyHive assigns them to
-   * organizations automatically, this endpoint returns a 403 for every request and the
+   * organizations automatically, this endpoint returns a 404 for every request and the
    * placement is not yours to make. Deployments whose administrators own the scope tree are
    * the ones this endpoint serves.
    *
@@ -385,8 +405,9 @@ class VirtualDataplanesNamespace {
     options?: FetchOptions,
   ): Promise<CreateVirtualDataplaneResponse> {
     const { org_id, ...body } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.POST('/v1/orgs/{org_id}/virtual_dataplanes', {
+      httpClient.POST('/v1/orgs/{org_id}/virtual_dataplanes', {
         params: { path: { org_id } },
         body,
         ...options,
@@ -413,8 +434,9 @@ class VirtualDataplanesNamespace {
     options?: FetchOptions,
   ): Promise<GetVirtualDataplaneResponse> {
     const { virtual_dataplane_id } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.GET('/v1/virtual_dataplanes/{virtual_dataplane_id}', {
+      httpClient.GET('/v1/virtual_dataplanes/{virtual_dataplane_id}', {
         params: { path: { virtual_dataplane_id } },
         ...options,
       }),
@@ -433,15 +455,16 @@ class VirtualDataplanesNamespace {
    * `name`, or sends the current one, changes nothing.
    *
    * This endpoint is unavailable where HoneyHive assigns virtual data planes automatically,
-   * and returns a 403 there.
+   * and returns a 404 there.
    */
   public update(
     request: UpdateVirtualDataplaneRequest,
     options?: FetchOptions,
   ): Promise<UpdateVirtualDataplaneResponse> {
     const { virtual_dataplane_id, ...body } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.PUT('/v1/virtual_dataplanes/{virtual_dataplane_id}', {
+      httpClient.PUT('/v1/virtual_dataplanes/{virtual_dataplane_id}', {
         params: { path: { virtual_dataplane_id } },
         body,
         ...options,
@@ -467,15 +490,16 @@ class VirtualDataplanesNamespace {
    * archived, so read that first if you need the list.
    *
    * This endpoint is unavailable where HoneyHive assigns virtual data planes automatically,
-   * and returns a 403 there.
+   * and returns a 404 there.
    */
   public delete(
     request: DeleteVirtualDataplaneRequest,
     options?: FetchOptions,
   ): Promise<DeleteVirtualDataplaneResponse> {
     const { virtual_dataplane_id, dangerously_delete_child_scopes } = request;
+    const httpClient = this.#clients.ControlPlaneApiKey;
     return unwrap(
-      this.#client.DELETE('/v1/virtual_dataplanes/{virtual_dataplane_id}', {
+      httpClient.DELETE('/v1/virtual_dataplanes/{virtual_dataplane_id}', {
         params: { path: { virtual_dataplane_id }, query: { dangerously_delete_child_scopes } },
         ...options,
       }),
@@ -484,17 +508,17 @@ class VirtualDataplanesNamespace {
 }
 
 export class Client {
-  #client: ReturnType<typeof createApiClient<paths>>;
+  #clients: ApiClients;
   readonly alerts: AlertsNamespace;
   readonly workspaces: WorkspacesNamespace;
   readonly projects: ProjectsNamespace;
   readonly virtualDataplanes: VirtualDataplanesNamespace;
 
   constructor(options: ClientConfig = {}) {
-    this.#client = createApiClient<paths>(options);
-    this.alerts = new AlertsNamespace(this.#client);
-    this.workspaces = new WorkspacesNamespace(this.#client);
-    this.projects = new ProjectsNamespace(this.#client);
-    this.virtualDataplanes = new VirtualDataplanesNamespace(this.#client);
+    this.#clients = createApiClient(options);
+    this.alerts = new AlertsNamespace(this.#clients);
+    this.workspaces = new WorkspacesNamespace(this.#clients);
+    this.projects = new ProjectsNamespace(this.#clients);
+    this.virtualDataplanes = new VirtualDataplanesNamespace(this.#clients);
   }
 }

package/src/generated/types.ts

@@ -244,12 +244,11 @@ export interface paths {
      *     A cluster admits an organization only if your control plane administrator configured it to,
      *     so a `cluster_id` you can read from a sibling virtual data plane is not necessarily one you
      *     may place a new virtual data plane on. A cluster that does not admit this organization
-     *     returns a 403. When you named the cluster, the fix is a configuration change your
-     *     administrator makes. When this endpoint inferred the cluster, send an explicit `cluster_id`
-     *     to place the virtual data plane on another cluster.
+     *     returns a 404. When this endpoint inferred the cluster, send an explicit `cluster_id` to
+     *     place the virtual data plane on another cluster.
      *
      *     Deployments differ in who places virtual data planes. Where HoneyHive assigns them to
-     *     organizations automatically, this endpoint returns a 403 for every request and the
+     *     organizations automatically, this endpoint returns a 404 for every request and the
      *     placement is not yours to make. Deployments whose administrators own the scope tree are
      *     the ones this endpoint serves.
      *
@@ -308,7 +307,7 @@ export interface paths {
      *     `name`, or sends the current one, changes nothing.
      *
      *     This endpoint is unavailable where HoneyHive assigns virtual data planes automatically,
-     *     and returns a 403 there.
+     *     and returns a 404 there.
      */
     put: operations['updateVirtualDataplane'];
     post?: never;
@@ -329,7 +328,7 @@ export interface paths {
      *     archived, so read that first if you need the list.
      *
      *     This endpoint is unavailable where HoneyHive assigns virtual data planes automatically,
-     *     and returns a 403 there.
+     *     and returns a 404 there.
      */
     delete: operations['deleteVirtualDataplane'];
     options?: never;
@@ -560,6 +559,8 @@ export interface components {
     PostVirtualDataplaneRequest: {
       /** @description Virtual dataplane display name. Allowed characters are letters, digits, space, underscore, hyphen, apostrophe and ampersand. The name must contain at least one letter or digit, and must not start with a space. */
       name: string;
+      /** @description Globally unique identifier for the virtual dataplane, letters, digits and underscores only. Omit it and the server derives one from the name with a random suffix appended. A slug already in use returns 409. */
+      slug?: string;
       /** @description Physical cluster to host this virtual dataplane. Omit to place it alongside the existing virtual dataplanes in this org; required when the org has none yet, or when its virtual dataplanes span more than one cluster. */
       cluster_id?: string;
       /**
@@ -607,6 +608,8 @@ export interface components {
     PostWorkspaceRequest: {
       /** @description Workspace display name. Allowed characters are letters, digits, space, underscore, hyphen, apostrophe and ampersand. The name must contain at least one letter or digit, and must not start with a space. */
       name: string;
+      /** @description Globally unique identifier for the workspace, letters, digits and underscores only. Omit it and the server derives one from the name with a random suffix appended. Supply it when the identifier has to match a value maintained outside HoneyHive, such as an identity provider group that grants access to this workspace. A slug already in use returns 409. */
+      slug?: string;
       /** @description Workspace description */
       description?: string;
       /**
@@ -899,6 +902,13 @@ export interface operations {
         };
         content?: never;
       };
+      /** @description The `slug` is already taken by another scope */
+      409: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content?: never;
+      };
     };
   };
   createProject: {
@@ -1196,15 +1206,15 @@ export interface operations {
         };
         content?: never;
       };
-      /** @description The caller may not create a virtual data plane here: the permission is missing at this organization, the API key's root scope does not contain it, this deployment assigns virtual data planes automatically, or the cluster (named or inferred) does not admit this organization */
-      403: {
+      /** @description Organization or cluster not found, or the caller may not create a virtual data plane here. The response does not say which. */
+      404: {
         headers: {
           [name: string]: unknown;
         };
         content?: never;
       };
-      /** @description Organization or cluster not found */
-      404: {
+      /** @description The `slug` is already taken by another scope */
+      409: {
         headers: {
           [name: string]: unknown;
         };
@@ -1274,14 +1284,7 @@ export interface operations {
         };
         content?: never;
       };
-      /** @description The caller may not update this virtual data plane, or this deployment assigns virtual data planes automatically */
-      403: {
-        headers: {
-          [name: string]: unknown;
-        };
-        content?: never;
-      };
-      /** @description Virtual data plane not found */
+      /** @description Virtual data plane not found, or the caller may not update it, or this deployment assigns virtual data planes automatically. The response does not say which. */
       404: {
         headers: {
           [name: string]: unknown;
@@ -1325,14 +1328,7 @@ export interface operations {
         };
         content?: never;
       };
-      /** @description The caller may not delete this virtual data plane, or this deployment assigns virtual data planes automatically */
-      403: {
-        headers: {
-          [name: string]: unknown;
-        };
-        content?: never;
-      };
-      /** @description Virtual data plane not found */
+      /** @description Virtual data plane not found, or the caller may not delete it, or this deployment assigns virtual data planes automatically. The response does not say which. */
       404: {
         headers: {
           [name: string]: unknown;

package/src/generated/version.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit manually. Run `pnpm turbo run generate` to regenerate.
 
-export const SDK_VERSION = '1.1.0';
+export const SDK_VERSION = '1.2.0';

package/src/util.ts

@@ -1,6 +1,9 @@
 import axios from 'axios';
 import createClient, { type ClientOptions, type Middleware } from 'openapi-fetch';
 
+import { checkControlPlaneApiKey, maskApiKey } from './apiKeys.js';
+import { type ApiClients } from './generated/client.js';
+import { type paths } from './generated/types.js';
 import { SDK_VERSION } from './generated/version.js';
 
 // The control plane's public, API-key entrypoint. This is deliberately not the
@@ -36,68 +39,6 @@ function getEnv(key: string, defaultValue?: string): string | undefined {
   return defaultValue;
 }
 
-/**
- * The prefix of a fine-grained control-plane API key, whose values have the
- * shape `hh_fgcp_<key id>_<key secret>`. In practice this is the only credential
- * the control plane's API accepts, but the SDK does not enforce that — the
- * prefix's job here is masking: it identifies the values whose key id can be
- * shown, and everything else is redacted wholesale.
- */
-const FGCP_KEY_PREFIX = 'hh_fgcp_';
-
-/**
- * The shape of the key id segment of a fine-grained key value: exactly 24
- * alphanumeric characters, with `_` and `-` excluded so that an id can never
- * read as two segments.
- *
- * The length and the alphabet are fixed properties of the key format, so a value
- * whose id segment doesn't match this either wasn't issued by HoneyHive or has
- * been altered in transit — either way it is redacted rather than rendered.
- */
-const FGCP_KEY_ID_PATTERN = /^[A-Za-z0-9]{24}$/;
-
-/**
- * Returns a display-safe rendering of an API key for verbose logging.
- *
- * Renders `hh_fgcp_<key id>_******` — the key's id and none of its secret. This
- * is character-for-character the masked form HoneyHive displays for that key, so
- * a verbose log line can be matched directly against a key in your account.
- * Masking from the id rather than from the secret is what makes it unique per
- * key and free of secret material.
- *
- * The id is `_`-free by construction, so it is everything up to the first `_`
- * after the prefix.
- *
- * Anything else collapses to 8 fixed-width asterisks, revealing neither its
- * length nor its content. That covers both a value that isn't a fine-grained key
- * at all — the SDK forwards whatever it is given, so this function must assume
- * it may be handed a coarse-grained HoneyHive key or a credential belonging to
- * some other system entirely — and a fine-grained value whose id segment is
- * truncated or mangled, where the characters after the prefix could be secret
- * material rather than an id.
- *
- * Both guards are load-bearing, and the prefix guard especially: without it the
- * unconditional slice below would chop 8 characters off an arbitrary token and
- * any value whose next 24 characters happened to be alphanumerics followed by
- * `_` would render as `hh_fgcp_<24 chars of that token>_******`, echoing part of
- * a foreign credential under our own prefix. So the output is always either
- * exactly the server's mask or fully redacted, never a partial echo.
- */
-function maskApiKey(apiKey: string): string {
-  if (!apiKey.startsWith(FGCP_KEY_PREFIX)) {
-    return '********';
-  }
-  const rest = apiKey.slice(FGCP_KEY_PREFIX.length);
-  const separator = rest.indexOf('_');
-  // An empty id never matches the pattern, so a value with no separator at all
-  // takes the redacted path without a second branch.
-  const keyId = separator === -1 ? '' : rest.slice(0, separator);
-  if (!FGCP_KEY_ID_PATTERN.test(keyId)) {
-    return '********';
-  }
-  return `${FGCP_KEY_PREFIX}${keyId}_******`;
-}
-
 /**
  * Configuration options for the HoneyHive Control Plane client. They extend the
  * options from openapi-fetch, but replace 'baseUrl' with 'controlPlaneUrl' so
@@ -106,9 +47,10 @@ function maskApiKey(apiKey: string): string {
 export interface ClientConfig extends Omit<ClientOptions, 'baseUrl' | 'headers'> {
   /**
    * A fine-grained control-plane API key (`hh_fgcp_…`), the only credential the
-   * control plane's API accepts in practice. Sent as a bearer token as-is; the
-   * control plane is what rejects a key it doesn't accept. Defaults to the
-   * `HH_CONTROL_PLANE_API_KEY` environment variable.
+   * control plane's API accepts. Defaults to the `HH_CONTROL_PLANE_API_KEY`
+   * environment variable. The value is trimmed, and one that is not a
+   * well-formed fine-grained key throws at construction, naming the option or
+   * variable it came from. An empty value counts as no key.
    */
   apiKey?: string;
   controlPlaneUrl?: string;
@@ -154,13 +96,18 @@ function querySerializer(queryParams: Record<string, unknown>): string {
   return uri.startsWith('?') ? uri.slice(1) : uri;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- needs to match openapi-fetch's own createClient<Paths extends {}> signature
-export function createApiClient<Paths extends {}>(
-  options: ClientConfig,
-): ReturnType<typeof createClient<Paths>> {
+/**
+ * Resolves the client's credential and returns the openapi-fetch client that
+ * carries it, keyed by the security scheme the spec defines. Every generated
+ * method indexes the result by its operation's scheme.
+ */
+export function createApiClient(options: ClientConfig): ApiClients {
   const { apiKey, controlPlaneUrl, middleware, verbose, _internal_provenance, ...clientOptions } =
     options;
-  const resolvedApiKey = apiKey ?? getEnv('HH_CONTROL_PLANE_API_KEY');
+  // Option > env var. The source travels with the value so the shape check
+  // below can name where a bad value came from.
+  const [rawApiKey, apiKeySource] =
+    apiKey !== undefined ? [apiKey, 'apiKey'] : [getEnv('HH_CONTROL_PLANE_API_KEY'), 'HH_CONTROL_PLANE_API_KEY']; // prettier-ignore
 
   // Resolution order: option > env var > default. For the option, any
   // non-undefined value wins (so explicit undefined falls back). For the env
@@ -177,14 +124,19 @@ export function createApiClient<Paths extends {}>(
     version: SDK_VERSION,
   };
 
-  // Log before the missing-key check so verbose users can see what *did*
-  // resolve when construction is about to fail.
+  // Log before either check that can throw (a malformed key, a missing key) so
+  // verbose users can see what *did* resolve when construction is about to
+  // fail. The mask redacts a malformed key wholesale.
   if (resolvedVerbose) {
     console.error(`Control plane URL: ${resolvedControlPlaneUrl}`);
-    console.error(`API key: ${resolvedApiKey ? maskApiKey(resolvedApiKey) : '(none)'}`);
+    console.error(`API key: ${rawApiKey ? maskApiKey(rawApiKey) : '(none)'}`);
     console.error(`Package: ${provenance.package} v${provenance.version}`);
   }
 
+  // A present key is checked for shape here, at construction, whether or not
+  // middleware is supplied. An empty key is no key (below), not a bad one.
+  const resolvedApiKey = rawApiKey ? checkControlPlaneApiKey(rawApiKey, apiKeySource) : rawApiKey;
+
   // When middleware is supplied, it is assumed to handle authentication itself
   // (for example by attaching a short-lived token per request), so no key is
   // required. The URL always resolves (option > env > default), so only the key
@@ -204,7 +156,7 @@ export function createApiClient<Paths extends {}>(
     headers.Authorization = `Bearer ${resolvedApiKey}`;
   }
 
-  const client = createClient<Paths>({
+  const client = createClient<paths>({
     ...clientOptions,
     querySerializer,
     // Always set (option > env > default). Middleware, when supplied, may still
@@ -221,7 +173,12 @@ export function createApiClient<Paths extends {}>(
     client.use(...middleware);
   }
 
-  return client;
+  // The control plane takes one credential kind, the fine-grained control
+  // plane key, so every scheme maps to the one client. Keyed by the schemes
+  // the spec defines, so a scheme added to or removed from the spec fails to
+  // compile here until this table says which client serves it.
+  const clients: ApiClients = { ControlPlaneApiKey: client };
+  return clients;
 }
 
 /**