@unkey/api 2.0.3 → 2.0.5

package/src/models/components/v2keysrerollkeyresponsedata.ts

@@ -0,0 +1,103 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type V2KeysRerollKeyResponseData = {
+  /**
+   * The unique identifier for the newly created key.
+   *
+   * @remarks
+   *
+   * This is NOT the actual API key token, but a reference ID for management operations.
+   * Store this ID to:
+   * - Update or revoke the key later
+   * - Track the key in your database
+   * - Display in admin dashboards (safe to log)
+   *
+   * Note: This is a new ID - the original key retains its own ID.
+   */
+  keyId: string;
+  /**
+   * The newly generated API key token (the actual secret that authenticates requests).
+   *
+   * @remarks
+   *
+   * **SECURITY CRITICAL:**
+   * - This is the only time you'll receive the complete key
+   * - Unkey stores only a hashed version (unless the original key was created with `recoverable=true`)
+   * - Never log, store, or expose this value in your systems
+   * - Transmit directly to the end user via secure channels only
+   * - If lost and not recoverable, you must reroll or create a new key
+   *
+   * The key format follows: `[prefix]_[random_bytes]`
+   * - Prefix is extracted from the original key or uses API default
+   * - Random bytes follow API configuration (default: 16 bytes)
+   *
+   * This is NOT the keyId - it's the actual secret token used for authentication.
+   */
+  key: string;
+};
+
+/** @internal */
+export const V2KeysRerollKeyResponseData$inboundSchema: z.ZodType<
+  V2KeysRerollKeyResponseData,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  keyId: z.string(),
+  key: z.string(),
+});
+
+/** @internal */
+export type V2KeysRerollKeyResponseData$Outbound = {
+  keyId: string;
+  key: string;
+};
+
+/** @internal */
+export const V2KeysRerollKeyResponseData$outboundSchema: z.ZodType<
+  V2KeysRerollKeyResponseData$Outbound,
+  z.ZodTypeDef,
+  V2KeysRerollKeyResponseData
+> = z.object({
+  keyId: z.string(),
+  key: z.string(),
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace V2KeysRerollKeyResponseData$ {
+  /** @deprecated use `V2KeysRerollKeyResponseData$inboundSchema` instead. */
+  export const inboundSchema = V2KeysRerollKeyResponseData$inboundSchema;
+  /** @deprecated use `V2KeysRerollKeyResponseData$outboundSchema` instead. */
+  export const outboundSchema = V2KeysRerollKeyResponseData$outboundSchema;
+  /** @deprecated use `V2KeysRerollKeyResponseData$Outbound` instead. */
+  export type Outbound = V2KeysRerollKeyResponseData$Outbound;
+}
+
+export function v2KeysRerollKeyResponseDataToJSON(
+  v2KeysRerollKeyResponseData: V2KeysRerollKeyResponseData,
+): string {
+  return JSON.stringify(
+    V2KeysRerollKeyResponseData$outboundSchema.parse(
+      v2KeysRerollKeyResponseData,
+    ),
+  );
+}
+
+export function v2KeysRerollKeyResponseDataFromJSON(
+  jsonString: string,
+): SafeParseResult<V2KeysRerollKeyResponseData, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => V2KeysRerollKeyResponseData$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'V2KeysRerollKeyResponseData' from JSON`,
+  );
+}

package/src/models/components/v2keyssetpermissionsresponsebody.ts

@@ -32,7 +32,6 @@ export type V2KeysSetPermissionsResponseBody = {
    * The response includes:
    * - The comprehensive, updated set of direct permissions (reflecting the complete replacement)
    * - Both ID and name for each permission for easy reference
-   * - Permissions sorted alphabetically by name for consistent response format
    *
    * Important notes:
    * - This only shows direct permissions, not those granted through roles

package/src/models/components/v2keyssetrolesresponsebody.ts

@@ -32,7 +32,6 @@ export type V2KeysSetRolesResponseBody = {
    * The response includes:
    * - The comprehensive, updated set of roles (reflecting the complete replacement)
    * - Both ID and name for each role for easy reference
-   * - Roles sorted alphabetically by name for consistent response format
    *
    * Important notes:
    * - This response shows the final state after the complete replacement

package/src/models/components/v2keysupdatekeyrequestbody.ts

@@ -6,18 +6,18 @@ import * as z from "zod";
 import { safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
-import {
-  KeyCreditsData,
-  KeyCreditsData$inboundSchema,
-  KeyCreditsData$Outbound,
-  KeyCreditsData$outboundSchema,
-} from "./keycreditsdata.js";
 import {
   RatelimitRequest,
   RatelimitRequest$inboundSchema,
   RatelimitRequest$Outbound,
   RatelimitRequest$outboundSchema,
 } from "./ratelimitrequest.js";
+import {
+  UpdateKeyCreditsData,
+  UpdateKeyCreditsData$inboundSchema,
+  UpdateKeyCreditsData$Outbound,
+  UpdateKeyCreditsData$outboundSchema,
+} from "./updatekeycreditsdata.js";
 
 export type V2KeysUpdateKeyRequestBody = {
   /**
@@ -68,7 +68,7 @@ export type V2KeysUpdateKeyRequestBody = {
   /**
    * Credit configuration and remaining balance for this key.
    */
-  credits?: KeyCreditsData | undefined;
+  credits?: UpdateKeyCreditsData | null | undefined;
   /**
    * Defines time-based rate limits that protect against abuse by controlling request frequency.
    *
@@ -102,7 +102,7 @@ export const V2KeysUpdateKeyRequestBody$inboundSchema: z.ZodType<
   externalId: z.nullable(z.string()).optional(),
   meta: z.nullable(z.record(z.any())).optional(),
   expires: z.nullable(z.number().int()).optional(),
-  credits: KeyCreditsData$inboundSchema.optional(),
+  credits: z.nullable(UpdateKeyCreditsData$inboundSchema).optional(),
   ratelimits: z.array(RatelimitRequest$inboundSchema).optional(),
   enabled: z.boolean().optional(),
   roles: z.array(z.string()).optional(),
@@ -116,7 +116,7 @@ export type V2KeysUpdateKeyRequestBody$Outbound = {
   externalId?: string | null | undefined;
   meta?: { [k: string]: any } | null | undefined;
   expires?: number | null | undefined;
-  credits?: KeyCreditsData$Outbound | undefined;
+  credits?: UpdateKeyCreditsData$Outbound | null | undefined;
   ratelimits?: Array<RatelimitRequest$Outbound> | undefined;
   enabled?: boolean | undefined;
   roles?: Array<string> | undefined;
@@ -134,7 +134,7 @@ export const V2KeysUpdateKeyRequestBody$outboundSchema: z.ZodType<
   externalId: z.nullable(z.string()).optional(),
   meta: z.nullable(z.record(z.any())).optional(),
   expires: z.nullable(z.number().int()).optional(),
-  credits: KeyCreditsData$outboundSchema.optional(),
+  credits: z.nullable(UpdateKeyCreditsData$outboundSchema).optional(),
   ratelimits: z.array(RatelimitRequest$outboundSchema).optional(),
   enabled: z.boolean().optional(),
   roles: z.array(z.string()).optional(),

package/src/models/errors/goneerrorresponse.ts

@@ -0,0 +1,118 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import * as components from "../components/index.js";
+import { UnkeyError } from "./unkeyerror.js";
+
+/**
+ * Error response when the requested resource has been soft-deleted and is no longer available. This occurs when:
+ *
+ * @remarks
+ * - The resource has been marked as deleted but still exists in the database
+ * - The resource is intentionally unavailable but could potentially be restored
+ * - The resource cannot be restored through the API or dashboard
+ *
+ * To resolve this error, contact support if you need the resource restored.
+ */
+export type GoneErrorResponseData = {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
+  meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
+  error: components.BaseError;
+};
+
+/**
+ * Error response when the requested resource has been soft-deleted and is no longer available. This occurs when:
+ *
+ * @remarks
+ * - The resource has been marked as deleted but still exists in the database
+ * - The resource is intentionally unavailable but could potentially be restored
+ * - The resource cannot be restored through the API or dashboard
+ *
+ * To resolve this error, contact support if you need the resource restored.
+ */
+export class GoneErrorResponse extends UnkeyError {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
+  meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
+  error: components.BaseError;
+
+  /** The original data that was passed to this error instance. */
+  data$: GoneErrorResponseData;
+
+  constructor(
+    err: GoneErrorResponseData,
+    httpMeta: { response: Response; request: Request; body: string },
+  ) {
+    const message = "message" in err && typeof err.message === "string"
+      ? err.message
+      : `API error occurred: ${JSON.stringify(err)}`;
+    super(message, httpMeta);
+    this.data$ = err;
+    this.meta = err.meta;
+    this.error = err.error;
+
+    this.name = "GoneErrorResponse";
+  }
+}
+
+/** @internal */
+export const GoneErrorResponse$inboundSchema: z.ZodType<
+  GoneErrorResponse,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  meta: components.Meta$inboundSchema,
+  error: components.BaseError$inboundSchema,
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
+})
+  .transform((v) => {
+    return new GoneErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
+  });
+
+/** @internal */
+export type GoneErrorResponse$Outbound = {
+  meta: components.Meta$Outbound;
+  error: components.BaseError$Outbound;
+};
+
+/** @internal */
+export const GoneErrorResponse$outboundSchema: z.ZodType<
+  GoneErrorResponse$Outbound,
+  z.ZodTypeDef,
+  GoneErrorResponse
+> = z.instanceof(GoneErrorResponse)
+  .transform(v => v.data$)
+  .pipe(z.object({
+    meta: components.Meta$outboundSchema,
+    error: components.BaseError$outboundSchema,
+  }));
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace GoneErrorResponse$ {
+  /** @deprecated use `GoneErrorResponse$inboundSchema` instead. */
+  export const inboundSchema = GoneErrorResponse$inboundSchema;
+  /** @deprecated use `GoneErrorResponse$outboundSchema` instead. */
+  export const outboundSchema = GoneErrorResponse$outboundSchema;
+  /** @deprecated use `GoneErrorResponse$Outbound` instead. */
+  export type Outbound = GoneErrorResponse$Outbound;
+}

package/src/models/errors/index.ts

@@ -6,6 +6,7 @@ export * from "./apierror.js";
 export * from "./badrequesterrorresponse.js";
 export * from "./conflicterrorresponse.js";
 export * from "./forbiddenerrorresponse.js";
+export * from "./goneerrorresponse.js";
 export * from "./httpclienterrors.js";
 export * from "./internalservererrorresponse.js";
 export * from "./notfounderrorresponse.js";

package/src/sdk/keys.ts

@@ -9,6 +9,7 @@ import { keysDeleteKey } from "../funcs/keysDeleteKey.js";
 import { keysGetKey } from "../funcs/keysGetKey.js";
 import { keysRemovePermissions } from "../funcs/keysRemovePermissions.js";
 import { keysRemoveRoles } from "../funcs/keysRemoveRoles.js";
+import { keysRerollKey } from "../funcs/keysRerollKey.js";
 import { keysSetPermissions } from "../funcs/keysSetPermissions.js";
 import { keysSetRoles } from "../funcs/keysSetRoles.js";
 import { keysUpdateCredits } from "../funcs/keysUpdateCredits.js";
@@ -233,6 +234,54 @@ export class Keys extends ClientSDK {
     ));
   }
 
+  /**
+   * Reroll Key
+   *
+   * @remarks
+   * Generate a new API key while preserving the configuration from an existing key.
+   *
+   * This operation creates a fresh key with a new token while maintaining all settings from the original key:
+   * - Permissions and roles
+   * - Custom metadata
+   * - Rate limit configurations
+   * - Identity associations
+   * - Remaining credits
+   * - Recovery settings
+   *
+   * **Key Generation:**
+   * - The system attempts to extract the prefix from the original key
+   * - If prefix extraction fails, the default API prefix is used
+   * - Key length follows the API's default byte configuration (or 16 bytes if not specified)
+   *
+   * **Original Key Handling:**
+   * - The original key will be revoked after the duration specified in `expiration`
+   * - Set `expiration` to 0 to revoke immediately
+   * - This allows for graceful key rotation with an overlap period
+   *
+   * Common use cases include:
+   * - Rotating keys for security compliance
+   * - Issuing replacement keys for compromised credentials
+   * - Creating backup keys with identical permissions
+   *
+   * **Important:** Analytics and usage metrics are tracked at both the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you to track usage across both individual keys and the overall identity.
+   *
+   * **Required Permissions**
+   *
+   *  Your root key must have:
+   *  - `api.*.create_key` or `api.<api_id>.create_key`
+   *  - `api.*.encrypt_key` or `api.<api_id>.encrypt_key` (only when the original key is recoverable)
+   */
+  async rerollKey(
+    request: components.V2KeysRerollKeyRequestBody,
+    options?: RequestOptions,
+  ): Promise<components.V2KeysRerollKeyResponseBody> {
+    return unwrapAsync(keysRerollKey(
+      this,
+      request,
+      options,
+    ));
+  }
+
   /**
    * Set key permissions
    *

package/src/sdk/permissions.ts

@@ -161,7 +161,8 @@ export class Permissions extends ClientSDK {
    * List permissions
    *
    * @remarks
-   * Retrieve all permissions in your workspace. Results are paginated and sorted alphabetically by permission name.
+   * Retrieve all permissions in your workspace.
+   * Results are paginated and sorted by their id.
    *
    * **Required Permissions**
    *
@@ -183,7 +184,8 @@ export class Permissions extends ClientSDK {
    * List roles
    *
    * @remarks
-   * Retrieve all roles in your workspace including their assigned permissions. Results are paginated and sorted alphabetically by role name.
+   * Retrieve all roles in your workspace including their assigned permissions.
+   * Results are paginated and sorted by their id.
    *
    * **Required Permissions**
    *

package/src/sdk/ratelimit.ts

@@ -66,7 +66,7 @@ export class Ratelimit extends ClientSDK {
    *
    * Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides.
    *
-   * **Important**: Always returns HTTP 200. Check the `success` field to determine if the request should proceed.
+   * **Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded - check the `success` field in the response to determine if the request should be allowed. 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
    *
    * **Required Permissions**
    *