@gscdump/contracts 3.7.0 → 3.8.0

package/README.md

@@ -3,7 +3,7 @@
 Shared protocol contracts for gscdump.com integrations.
 
 Use `@gscdump/contracts/v1` for operation definitions, request and response schemas, and protocol constants.
-The registry describes 55 HTTP operations and the realtime protocol.
+The registry describes 58 HTTP operations and the realtime protocol.
 For HTTP calls, install [`@gscdump/sdk`](../sdk/README.md).
 
 ```bash

package/dist/v1/http-core.d.mts

@@ -11,7 +11,7 @@ export declare const HTTP_V1_CREDENTIAL_SCOPES: {
   readonly user_key: readonly ["users:read", "users:write", "sites:read", "sites:write", "analytics:read", "analytics:execute", "indexing:read", "indexing:write", "sitemaps:read", "sitemaps:write", "settings:read", "settings:write", "realtime:connect"];
   readonly partner_key: readonly ["users:read", "users:write", "sites:read", "sites:write", "analytics:read", "analytics:execute", "indexing:read", "indexing:write", "sitemaps:read", "sitemaps:write", "settings:read", "settings:write", "realtime:connect", "teams:read", "teams:write"];
 };
-export declare const HTTP_V1_ERROR_CODES: readonly ["invalid_request", "unauthorized", "forbidden", "user_not_found", "site_not_found", "rate_limited", "realtime_unavailable", "internal_error", "contract_violation"];
+export declare const HTTP_V1_ERROR_CODES: readonly ["invalid_request", "unauthorized", "forbidden", "user_not_found", "site_not_found", "api_key_not_found", "api_key_limit_reached", "rate_limited", "realtime_unavailable", "internal_error", "contract_violation"];
 export type HttpV1SurfaceName = HttpV1RouteSurfaceName;
 export type HttpV1Method = HttpV1RouteMethod;
 export type HttpV1Credential = typeof HTTP_V1_CREDENTIALS[number];

package/dist/v1/http-core.mjs

@@ -41,6 +41,8 @@ const HTTP_V1_ERROR_CODES = [
 	"forbidden",
 	"user_not_found",
 	"site_not_found",
+	"api_key_not_found",
+	"api_key_limit_reached",
 	"rate_limited",
 	"realtime_unavailable",
 	"internal_error",
@@ -104,7 +106,7 @@ function assertPathContract(operation) {
 	if (names.join("\0") !== schemaKeys.join("\0")) throw new TypeError(`${operation.id}: params schema keys (${schemaKeys.join(", ")}) must match path order (${names.join(", ")})`);
 }
 function assertOperation(operation) {
-	if (!/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/.test(operation.id)) throw new TypeError(`${operation.id}: operation ID must be a stable dotted lowercase identifier`);
+	if (!/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:_[a-z0-9]+)*)+$/.test(operation.id)) throw new TypeError(`${operation.id}: operation ID must be a stable dotted lowercase identifier`);
 	if (!isSafePathTemplate(operation.path)) throw new TypeError(`${operation.id}: path must be a safe literal surface-relative template`);
 	assertRequestLocations(operation.request, operation.id);
 	assertPathContract(operation);

package/dist/v1/operations.d.mts

@@ -697,6 +697,8 @@ export declare function createGscdumpV1Protocol(): {
           forbidden: "forbidden";
           user_not_found: "user_not_found";
           site_not_found: "site_not_found";
+          api_key_not_found: "api_key_not_found";
+          api_key_limit_reached: "api_key_limit_reached";
           rate_limited: "rate_limited";
           realtime_unavailable: "realtime_unavailable";
           contract_violation: "contract_violation";
@@ -715,6 +717,8 @@ export declare function createGscdumpV1Protocol(): {
           forbidden: "forbidden";
           user_not_found: "user_not_found";
           site_not_found: "site_not_found";
+          api_key_not_found: "api_key_not_found";
+          api_key_limit_reached: "api_key_limit_reached";
           rate_limited: "rate_limited";
           realtime_unavailable: "realtime_unavailable";
           contract_violation: "contract_violation";
@@ -12824,6 +12828,410 @@ export declare function createGscdumpV1Protocol(): {
         readonly method: "POST";
         readonly path: "/users/{userId}/sites/verify";
       };
+      readonly createUserApiKey: {
+        readonly visibility: "public";
+        readonly semantics: {
+          readonly kind: "mutation";
+          readonly sideEffects: "state";
+          readonly idempotent: false;
+          readonly retry: "never";
+          readonly readConsistency: null;
+        };
+        readonly auth: {
+          readonly credentials: readonly ["partner_key"];
+          readonly scopes: readonly ["users:write"];
+          readonly ownership: readonly [{
+            readonly credential: "partner_key";
+            readonly rule: "linked_user";
+          }];
+        };
+        readonly request: {
+          readonly params: z.ZodObject<{
+            userId: z.ZodString;
+          }, z.core.$strict>;
+          readonly query: null;
+          readonly headers: z.ZodObject<{
+            'x-request-id': z.ZodOptional<z.ZodString>;
+          }, z.core.$strict>;
+          readonly body: z.ZodObject<{
+            label: z.ZodString;
+          }, z.core.$strict>;
+        };
+        readonly responses: {
+          readonly 201: CompatibleResponseSchema<z.ZodObject<{
+            data: z.ZodObject<{
+              readonly keyId: z.ZodString;
+              readonly apiKey: z.ZodString;
+              readonly preview: z.ZodString;
+              readonly label: z.ZodString;
+              readonly createdAt: z.ZodNumber;
+            }, z.core.$strip>;
+            meta: z.ZodObject<{
+              readonly requestId: z.ZodString;
+              readonly surface: z.ZodLiteral<"partner">;
+              readonly version: z.ZodLiteral<"1.0">;
+            }, z.core.$strip>;
+          }, z.core.$strip>, z.ZodObject<{
+            data: z.ZodObject<{
+              readonly keyId: z.ZodString;
+              readonly apiKey: z.ZodString;
+              readonly preview: z.ZodString;
+              readonly label: z.ZodString;
+              readonly createdAt: z.ZodNumber;
+            }, z.core.$strip>;
+            meta: z.ZodObject<{
+              readonly requestId: z.ZodString;
+              readonly surface: z.ZodLiteral<"partner">;
+              readonly version: z.ZodLiteral<"1.0">;
+            }, z.core.$strip>;
+          }, z.core.$strip>>;
+        };
+        readonly errors: readonly ["invalid_request", "unauthorized", "forbidden", "user_not_found", "rate_limited", "internal_error", "contract_violation", "api_key_limit_reached"];
+        readonly errorResponse: CompatibleResponseSchema<z.ZodObject<{
+          readonly error: z.ZodObject<{
+            code: z.ZodEnum<{
+              internal_error: "internal_error";
+              invalid_request: "invalid_request";
+              unauthorized: "unauthorized";
+              forbidden: "forbidden";
+              user_not_found: "user_not_found";
+              api_key_limit_reached: "api_key_limit_reached";
+              rate_limited: "rate_limited";
+              contract_violation: "contract_violation";
+            }>;
+            message: z.ZodString;
+            requestId: z.ZodString;
+            retryable: z.ZodBoolean;
+            details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+          }, z.core.$strict>;
+        }, z.core.$strip>, z.ZodObject<{
+          readonly error: z.ZodObject<{
+            code: z.ZodEnum<{
+              internal_error: "internal_error";
+              invalid_request: "invalid_request";
+              unauthorized: "unauthorized";
+              forbidden: "forbidden";
+              user_not_found: "user_not_found";
+              api_key_limit_reached: "api_key_limit_reached";
+              rate_limited: "rate_limited";
+              contract_violation: "contract_violation";
+            }>;
+            message: z.ZodString;
+            requestId: z.ZodString;
+            retryable: z.ZodBoolean;
+            details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+          }, z.core.$loose>;
+        }, z.core.$strip>>;
+        readonly resources: {
+          readonly reads: readonly [{
+            readonly type: "partner.user";
+            readonly idFrom: "params.userId";
+          }];
+          readonly changes: readonly [{
+            readonly type: "partner.user";
+            readonly idFrom: "params.userId";
+          }];
+        };
+        readonly lifecycle: {
+          readonly introduced: "3.8.0";
+        };
+        readonly docs: {
+          readonly summary: "Create a user API key";
+          readonly description: "Issues a new revocable API key for a partner-linked user. The raw key appears only in this response; store or show it once. Each partner may hold at most 10 API keys per user; a create beyond the limit fails with `409 api_key_limit_reached`.";
+          readonly tags: readonly ["Users"];
+          readonly examples: {
+            readonly request: {
+              readonly params: {
+                readonly userId: "u_01";
+              };
+              readonly body: {
+                readonly label: "Laptop CLI";
+              };
+            };
+            readonly response: {
+              readonly data: {
+                readonly keyId: "ak_01";
+                readonly apiKey: "gsd_user_0123456789abcdef";
+                readonly preview: "gsd_user_012345...cdef";
+                readonly label: "Laptop CLI";
+                readonly createdAt: 1789516800;
+              };
+              readonly meta: {
+                readonly requestId: "req_01";
+                readonly surface: "partner";
+                readonly version: "1.0";
+              };
+            };
+          };
+        };
+        readonly id: "partner.users.api_keys.create";
+        readonly method: "POST";
+        readonly path: "/users/{userId}/api-keys";
+      };
+      readonly listUserApiKeys: {
+        readonly visibility: "public";
+        readonly semantics: {
+          readonly kind: "query";
+          readonly sideEffects: "none";
+          readonly idempotent: true;
+          readonly retry: "idempotent";
+          readonly readConsistency: "primary";
+        };
+        readonly auth: {
+          readonly credentials: readonly ["partner_key"];
+          readonly scopes: readonly ["users:read"];
+          readonly ownership: readonly [{
+            readonly credential: "partner_key";
+            readonly rule: "linked_user";
+          }];
+        };
+        readonly request: {
+          readonly params: z.ZodObject<{
+            userId: z.ZodString;
+          }, z.core.$strict>;
+          readonly query: null;
+          readonly headers: z.ZodObject<{
+            'x-request-id': z.ZodOptional<z.ZodString>;
+          }, z.core.$strict>;
+          readonly body: null;
+        };
+        readonly responses: {
+          readonly 200: CompatibleResponseSchema<z.ZodObject<{
+            data: z.ZodObject<{
+              readonly keys: z.ZodArray<z.ZodObject<{
+                readonly keyId: z.ZodString;
+                readonly preview: z.ZodString;
+                readonly label: z.ZodString;
+                readonly createdAt: z.ZodNumber;
+                readonly lastUsedAt: z.ZodNullable<z.ZodNumber>;
+              }, z.core.$strip>>;
+            }, z.core.$strip>;
+            meta: z.ZodObject<{
+              readonly requestId: z.ZodString;
+              readonly surface: z.ZodLiteral<"partner">;
+              readonly version: z.ZodLiteral<"1.0">;
+            }, z.core.$strip>;
+          }, z.core.$strip>, z.ZodObject<{
+            data: z.ZodObject<{
+              readonly keys: z.ZodArray<z.ZodObject<{
+                readonly keyId: z.ZodString;
+                readonly preview: z.ZodString;
+                readonly label: z.ZodString;
+                readonly createdAt: z.ZodNumber;
+                readonly lastUsedAt: z.ZodNullable<z.ZodNumber>;
+              }, z.core.$strip>>;
+            }, z.core.$strip>;
+            meta: z.ZodObject<{
+              readonly requestId: z.ZodString;
+              readonly surface: z.ZodLiteral<"partner">;
+              readonly version: z.ZodLiteral<"1.0">;
+            }, z.core.$strip>;
+          }, z.core.$strip>>;
+        };
+        readonly errors: readonly ["invalid_request", "unauthorized", "forbidden", "user_not_found", "rate_limited", "internal_error", "contract_violation"];
+        readonly errorResponse: CompatibleResponseSchema<z.ZodObject<{
+          readonly error: z.ZodObject<{
+            code: z.ZodEnum<{
+              internal_error: "internal_error";
+              invalid_request: "invalid_request";
+              unauthorized: "unauthorized";
+              forbidden: "forbidden";
+              user_not_found: "user_not_found";
+              rate_limited: "rate_limited";
+              contract_violation: "contract_violation";
+            }>;
+            message: z.ZodString;
+            requestId: z.ZodString;
+            retryable: z.ZodBoolean;
+            details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+          }, z.core.$strict>;
+        }, z.core.$strip>, z.ZodObject<{
+          readonly error: z.ZodObject<{
+            code: z.ZodEnum<{
+              internal_error: "internal_error";
+              invalid_request: "invalid_request";
+              unauthorized: "unauthorized";
+              forbidden: "forbidden";
+              user_not_found: "user_not_found";
+              rate_limited: "rate_limited";
+              contract_violation: "contract_violation";
+            }>;
+            message: z.ZodString;
+            requestId: z.ZodString;
+            retryable: z.ZodBoolean;
+            details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+          }, z.core.$loose>;
+        }, z.core.$strip>>;
+        readonly resources: {
+          readonly reads: readonly [{
+            readonly type: "partner.user";
+            readonly idFrom: "params.userId";
+          }];
+          readonly changes: readonly [];
+        };
+        readonly lifecycle: {
+          readonly introduced: "3.8.0";
+        };
+        readonly docs: {
+          readonly summary: "List user API keys";
+          readonly description: "Lists the active API keys the authenticated partner issued for a user. Keys issued by other partners or by the user are excluded. Raw keys are never returned.";
+          readonly tags: readonly ["Users"];
+          readonly examples: {
+            readonly request: {
+              readonly params: {
+                readonly userId: "u_01";
+              };
+            };
+            readonly response: {
+              readonly data: {
+                readonly keys: readonly [{
+                  readonly keyId: "ak_01";
+                  readonly preview: "gsd_user_012345...cdef";
+                  readonly label: "Laptop CLI";
+                  readonly createdAt: 1789516800;
+                  readonly lastUsedAt: null;
+                }];
+              };
+              readonly meta: {
+                readonly requestId: "req_01";
+                readonly surface: "partner";
+                readonly version: "1.0";
+              };
+            };
+          };
+        };
+        readonly id: "partner.users.api_keys.list";
+        readonly method: "GET";
+        readonly path: "/users/{userId}/api-keys";
+      };
+      readonly revokeUserApiKey: {
+        readonly visibility: "public";
+        readonly semantics: {
+          readonly kind: "mutation";
+          readonly sideEffects: "state";
+          readonly idempotent: true;
+          readonly retry: "idempotent";
+          readonly readConsistency: null;
+        };
+        readonly auth: {
+          readonly credentials: readonly ["partner_key"];
+          readonly scopes: readonly ["users:write"];
+          readonly ownership: readonly [{
+            readonly credential: "partner_key";
+            readonly rule: "linked_user";
+          }];
+        };
+        readonly request: {
+          readonly params: z.ZodObject<{
+            userId: z.ZodString;
+            keyId: z.ZodString;
+          }, z.core.$strict>;
+          readonly query: null;
+          readonly headers: z.ZodObject<{
+            'x-request-id': z.ZodOptional<z.ZodString>;
+          }, z.core.$strict>;
+          readonly body: null;
+        };
+        readonly responses: {
+          readonly 200: CompatibleResponseSchema<z.ZodObject<{
+            data: z.ZodObject<{
+              readonly ok: z.ZodLiteral<true>;
+              readonly keyId: z.ZodString;
+            }, z.core.$strip>;
+            meta: z.ZodObject<{
+              readonly requestId: z.ZodString;
+              readonly surface: z.ZodLiteral<"partner">;
+              readonly version: z.ZodLiteral<"1.0">;
+            }, z.core.$strip>;
+          }, z.core.$strip>, z.ZodObject<{
+            data: z.ZodObject<{
+              readonly ok: z.ZodLiteral<true>;
+              readonly keyId: z.ZodString;
+            }, z.core.$strip>;
+            meta: z.ZodObject<{
+              readonly requestId: z.ZodString;
+              readonly surface: z.ZodLiteral<"partner">;
+              readonly version: z.ZodLiteral<"1.0">;
+            }, z.core.$strip>;
+          }, z.core.$strip>>;
+        };
+        readonly errors: readonly ["invalid_request", "unauthorized", "forbidden", "user_not_found", "rate_limited", "internal_error", "contract_violation", "api_key_not_found"];
+        readonly errorResponse: CompatibleResponseSchema<z.ZodObject<{
+          readonly error: z.ZodObject<{
+            code: z.ZodEnum<{
+              internal_error: "internal_error";
+              invalid_request: "invalid_request";
+              unauthorized: "unauthorized";
+              forbidden: "forbidden";
+              user_not_found: "user_not_found";
+              api_key_not_found: "api_key_not_found";
+              rate_limited: "rate_limited";
+              contract_violation: "contract_violation";
+            }>;
+            message: z.ZodString;
+            requestId: z.ZodString;
+            retryable: z.ZodBoolean;
+            details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+          }, z.core.$strict>;
+        }, z.core.$strip>, z.ZodObject<{
+          readonly error: z.ZodObject<{
+            code: z.ZodEnum<{
+              internal_error: "internal_error";
+              invalid_request: "invalid_request";
+              unauthorized: "unauthorized";
+              forbidden: "forbidden";
+              user_not_found: "user_not_found";
+              api_key_not_found: "api_key_not_found";
+              rate_limited: "rate_limited";
+              contract_violation: "contract_violation";
+            }>;
+            message: z.ZodString;
+            requestId: z.ZodString;
+            retryable: z.ZodBoolean;
+            details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+          }, z.core.$loose>;
+        }, z.core.$strip>>;
+        readonly resources: {
+          readonly reads: readonly [{
+            readonly type: "partner.user";
+            readonly idFrom: "params.userId";
+          }];
+          readonly changes: readonly [{
+            readonly type: "partner.user";
+            readonly idFrom: "params.userId";
+          }];
+        };
+        readonly lifecycle: {
+          readonly introduced: "3.8.0";
+        };
+        readonly docs: {
+          readonly summary: "Revoke a user API key";
+          readonly description: "Revokes an API key the authenticated partner issued for a user. The key stops working immediately. Revoking an already revoked key succeeds again. An unknown key, or a key issued by another partner or by the user, fails with `404 api_key_not_found`.";
+          readonly tags: readonly ["Users"];
+          readonly examples: {
+            readonly request: {
+              readonly params: {
+                readonly userId: "u_01";
+                readonly keyId: "ak_01";
+              };
+            };
+            readonly response: {
+              readonly data: {
+                readonly ok: true;
+                readonly keyId: "ak_01";
+              };
+              readonly meta: {
+                readonly requestId: "req_01";
+                readonly surface: "partner";
+                readonly version: "1.0";
+              };
+            };
+          };
+        };
+        readonly id: "partner.users.api_keys.revoke";
+        readonly method: "DELETE";
+        readonly path: "/users/{userId}/api-keys/{keyId}";
+      };
     }>;
     analytics: HttpV1Surface<{
       readonly queryRows: {

package/dist/v1/operations.mjs

@@ -348,6 +348,33 @@ function createGscdumpV1Protocol() {
 		updated: z.boolean(),
 		sites: z.array(gscdumpAvailableSiteSchema)
 	}), partnerResponseMeta);
+	const partnerUserApiKeyLabel = z.string().min(1).max(64);
+	const partnerUserApiKeyId = z.string().regex(/^ak_[\w-]+$/);
+	const partnerUserApiKeyParams = z.strictObject({
+		userId: realtimeSchemas.publicUserId,
+		keyId: partnerUserApiKeyId
+	});
+	const createUserApiKeyRequest = z.strictObject({ label: z.string().trim().min(1).max(64) });
+	const partnerUserApiKeyCreatedAt = z.number().int().nonnegative();
+	const createUserApiKeyResponse = defineSuccessResponse(defineResponseObject({
+		keyId: partnerUserApiKeyId,
+		apiKey: z.string().regex(/^gsd_user_[\w-]+$/),
+		preview: z.string().min(1),
+		label: partnerUserApiKeyLabel,
+		createdAt: partnerUserApiKeyCreatedAt
+	}), partnerResponseMeta);
+	const partnerUserApiKey = defineResponseObject({
+		keyId: partnerUserApiKeyId,
+		preview: z.string().min(1),
+		label: partnerUserApiKeyLabel,
+		createdAt: partnerUserApiKeyCreatedAt,
+		lastUsedAt: z.number().int().nonnegative().nullable()
+	});
+	const listUserApiKeysResponse = defineSuccessResponse(defineResponseObject({ keys: z.array(partnerUserApiKey.producer) }, { keys: z.array(partnerUserApiKey.client) }), partnerResponseMeta);
+	const revokeUserApiKeyResponse = defineSuccessResponse(defineResponseObject({
+		ok: z.literal(true),
+		keyId: partnerUserApiKeyId
+	}), partnerResponseMeta);
 	const trendQuery = z.strictObject({
 		startDate: calendarDate,
 		endDate: calendarDate,
@@ -681,6 +708,8 @@ function createGscdumpV1Protocol() {
 		"internal_error",
 		"contract_violation"
 	];
+	const partnerUserApiKeyCreateErrors = [...partnerUserErrors, "api_key_limit_reached"];
+	const partnerUserApiKeyRevokeErrors = [...partnerUserErrors, "api_key_not_found"];
 	const analyticsRowsErrors = [
 		"invalid_request",
 		"unauthorized",
@@ -4109,6 +4138,189 @@ function createGscdumpV1Protocol() {
 						}
 					}
 				}
+			}),
+			createUserApiKey: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.users.api_keys.create"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: false,
+					retry: "never",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["users:write"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "linked_user"
+					}]
+				},
+				request: {
+					params: z.strictObject({ userId: realtimeSchemas.publicUserId }),
+					query: null,
+					headers: requestHeaders,
+					body: createUserApiKeyRequest
+				},
+				responses: { 201: createUserApiKeyResponse },
+				errors: partnerUserApiKeyCreateErrors,
+				errorResponse: errorEnvelopeSchemas(partnerUserApiKeyCreateErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "partner.user",
+						idFrom: "params.userId"
+					}],
+					changes: [{
+						type: "partner.user",
+						idFrom: "params.userId"
+					}]
+				},
+				lifecycle: { introduced: "3.8.0" },
+				docs: {
+					summary: "Create a user API key",
+					description: "Issues a new revocable API key for a partner-linked user. The raw key appears only in this response; store or show it once. Each partner may hold at most 10 API keys per user; a create beyond the limit fails with `409 api_key_limit_reached`.",
+					tags: ["Users"],
+					examples: {
+						request: {
+							params: { userId: "u_01" },
+							body: { label: "Laptop CLI" }
+						},
+						response: {
+							data: {
+								keyId: "ak_01",
+								apiKey: "gsd_user_0123456789abcdef",
+								preview: "gsd_user_012345...cdef",
+								label: "Laptop CLI",
+								createdAt: 1789516800
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
+			listUserApiKeys: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.users.api_keys.list"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["users:read"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "linked_user"
+					}]
+				},
+				request: {
+					params: z.strictObject({ userId: realtimeSchemas.publicUserId }),
+					query: null,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: listUserApiKeysResponse },
+				errors: partnerUserErrors,
+				errorResponse: errorEnvelopeSchemas(partnerUserErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "partner.user",
+						idFrom: "params.userId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "3.8.0" },
+				docs: {
+					summary: "List user API keys",
+					description: "Lists the active API keys the authenticated partner issued for a user. Keys issued by other partners or by the user are excluded. Raw keys are never returned.",
+					tags: ["Users"],
+					examples: {
+						request: { params: { userId: "u_01" } },
+						response: {
+							data: { keys: [{
+								keyId: "ak_01",
+								preview: "gsd_user_012345...cdef",
+								label: "Laptop CLI",
+								createdAt: 1789516800,
+								lastUsedAt: null
+							}] },
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
+			revokeUserApiKey: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.users.api_keys.revoke"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["users:write"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "linked_user"
+					}]
+				},
+				request: {
+					params: partnerUserApiKeyParams,
+					query: null,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: revokeUserApiKeyResponse },
+				errors: partnerUserApiKeyRevokeErrors,
+				errorResponse: errorEnvelopeSchemas(partnerUserApiKeyRevokeErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "partner.user",
+						idFrom: "params.userId"
+					}],
+					changes: [{
+						type: "partner.user",
+						idFrom: "params.userId"
+					}]
+				},
+				lifecycle: { introduced: "3.8.0" },
+				docs: {
+					summary: "Revoke a user API key",
+					description: "Revokes an API key the authenticated partner issued for a user. The key stops working immediately. Revoking an already revoked key succeeds again. An unknown key, or a key issued by another partner or by the user, fails with `404 api_key_not_found`.",
+					tags: ["Users"],
+					examples: {
+						request: { params: {
+							userId: "u_01",
+							keyId: "ak_01"
+						} },
+						response: {
+							data: {
+								ok: true,
+								keyId: "ak_01"
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
 			})
 		}
 	});

package/dist/v1/route-catalog.d.mts

@@ -266,6 +266,21 @@ export declare const GSCDUMP_V1_ROUTE_CATALOG: {
       readonly method: "POST";
       readonly template: "/users/{userId}/sites/verify";
     };
+    readonly 'partner.users.api_keys.create': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/users/{userId}/api-keys";
+    };
+    readonly 'partner.users.api_keys.list': {
+      readonly surface: "partner";
+      readonly method: "GET";
+      readonly template: "/users/{userId}/api-keys";
+    };
+    readonly 'partner.users.api_keys.revoke': {
+      readonly surface: "partner";
+      readonly method: "DELETE";
+      readonly template: "/users/{userId}/api-keys/{keyId}";
+    };
     readonly 'analytics.rows.query': {
       readonly surface: "analytics";
       readonly method: "POST";

package/dist/v1/route-catalog.mjs

@@ -253,6 +253,21 @@ const GSCDUMP_V1_ROUTE_CATALOG = {
 			method: "POST",
 			template: "/users/{userId}/sites/verify"
 		},
+		"partner.users.api_keys.create": {
+			surface: "partner",
+			method: "POST",
+			template: "/users/{userId}/api-keys"
+		},
+		"partner.users.api_keys.list": {
+			surface: "partner",
+			method: "GET",
+			template: "/users/{userId}/api-keys"
+		},
+		"partner.users.api_keys.revoke": {
+			surface: "partner",
+			method: "DELETE",
+			template: "/users/{userId}/api-keys/{keyId}"
+		},
 		"analytics.rows.query": {
 			surface: "analytics",
 			method: "POST",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/contracts",
   "type": "module",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Shared gscdump.com API, webhook, realtime, and lifecycle contracts.",
   "author": {
     "name": "Harlan Wilton",