@unkey/api/src/models/components/v2keyscreatekeyrequestbody.ts

Developer-friendly & type-safe Typescript SDK specifically catered to leverage *@unkey/api* API.

/*
 * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
 */

import * as z from "zod/v3";
import {
  KeyCreditsData,
  KeyCreditsData$Outbound,
  KeyCreditsData$outboundSchema,
} from "./keycreditsdata.js";
import {
  RatelimitRequest,
  RatelimitRequest$Outbound,
  RatelimitRequest$outboundSchema,
} from "./ratelimitrequest.js";

export type V2KeysCreateKeyRequestBody = {
  /**
   * The API namespace this key belongs to.
   *
   * @remarks
   * Keys from different APIs cannot access each other.
   */
  apiId: string;
  /**
   * Adds a visual identifier to the beginning of the generated key for easier recognition in logs and dashboards.
   *
   * @remarks
   * The prefix becomes part of the actual key string (e.g., `prod_xxxxxxxxx`).
   * Avoid using sensitive information in prefixes as they may appear in logs and error messages.
   */
  prefix?: string | undefined;
  /**
   * Sets a human-readable identifier for internal organization and dashboard display.
   *
   * @remarks
   * Never exposed to end users, only visible in management interfaces and API responses.
   * Avoid generic names like "API Key" when managing multiple keys for the same user or service.
   */
  name?: string | undefined;
  /**
   * Controls the cryptographic strength of the generated key in bytes.
   *
   * @remarks
   * Higher values increase security but result in longer keys that may be more annoying to handle.
   * The default 16 bytes provides 2^128 possible combinations, sufficient for most applications.
   * Consider 32 bytes for highly sensitive APIs, but avoid values above 64 bytes unless specifically required.
   */
  byteLength?: number | undefined;
  /**
   * Links this key to a user or entity in your system using your own identifier.
   *
   * @remarks
   * Returned during verification to identify the key owner without additional database lookups.
   * Essential for user-specific analytics, billing, and multi-tenant key management.
   * Use your primary user ID, organization ID, or tenant ID for best results.
   * Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
   */
  externalId?: string | undefined;
  /**
   * Stores arbitrary JSON metadata returned during key verification for contextual information.
   *
   * @remarks
   * Eliminates additional database lookups during verification, improving performance for stateless services.
   * Avoid storing sensitive data here as it's returned in verification responses.
   * Large metadata objects increase verification latency and should stay under 10KB total size.
   */
  meta?: { [k: string]: any } | undefined;
  /**
   * Assigns existing roles to this key for permission management through role-based access control.
   *
   * @remarks
   * Roles must already exist in your workspace before assignment.
   * During verification, all permissions from assigned roles are checked against requested permissions.
   * Roles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.
   */
  roles?: Array<string> | undefined;
  /**
   * Grants specific permissions directly to this key without requiring role membership.
   *
   * @remarks
   * Wildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.
   * Direct permissions supplement any permissions inherited from assigned roles.
   */
  permissions?: Array<string> | undefined;
  /**
   * Sets when this key automatically expires as a Unix timestamp in milliseconds.
   *
   * @remarks
   * Verification fails with code=EXPIRED immediately after this time passes.
   * Omitting this field creates a permanent key that never expires.
   *
   * Avoid setting timestamps in the past as they immediately invalidate the key.
   * Keys expire based on server time, not client time, which prevents timezone-related issues.
   * Essential for trial periods, temporary access, and security compliance requiring key rotation.
   */
  expires?: number | undefined;
  /**
   * Credit configuration and remaining balance for this key.
   */
  credits?: KeyCreditsData | undefined;
  /**
   * Defines time-based rate limits that protect against abuse by controlling request frequency.
   *
   * @remarks
   * Unlike credits which track total usage, rate limits reset automatically after each window expires.
   * Multiple rate limits can control different operation types with separate thresholds and windows.
   * Essential for preventing API abuse while maintaining good performance for legitimate usage.
   */
  ratelimits?: Array<RatelimitRequest> | undefined;
  /**
   * Controls whether the key is active immediately upon creation.
   *
   * @remarks
   * When set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.
   * Useful for pre-creating keys that will be activated later or for keys requiring manual approval.
   * Most keys should be created with `enabled=true` for immediate use.
   */
  enabled?: boolean | undefined;
  /**
   * Controls whether the plaintext key is stored in an encrypted vault for later retrieval.
   *
   * @remarks
   * When true, allows recovering the actual key value using keys.getKey with decrypt=true.
   * When false, the key value cannot be retrieved after creation for maximum security.
   * Only enable for development keys or when key recovery is absolutely necessary.
   */
  recoverable?: boolean | undefined;
};

/** @internal */
export type V2KeysCreateKeyRequestBody$Outbound = {
  apiId: string;
  prefix?: string | undefined;
  name?: string | undefined;
  byteLength: number;
  externalId?: string | undefined;
  meta?: { [k: string]: any } | undefined;
  roles?: Array<string> | undefined;
  permissions?: Array<string> | undefined;
  expires?: number | undefined;
  credits?: KeyCreditsData$Outbound | undefined;
  ratelimits?: Array<RatelimitRequest$Outbound> | undefined;
  enabled: boolean;
  recoverable: boolean;
};

/** @internal */
export const V2KeysCreateKeyRequestBody$outboundSchema: z.ZodType<
  V2KeysCreateKeyRequestBody$Outbound,
  z.ZodTypeDef,
  V2KeysCreateKeyRequestBody
> = z.object({
  apiId: z.string(),
  prefix: z.string().optional(),
  name: z.string().optional(),
  byteLength: z.number().int().default(16),
  externalId: z.string().optional(),
  meta: z.record(z.any()).optional(),
  roles: z.array(z.string()).optional(),
  permissions: z.array(z.string()).optional(),
  expires: z.number().int().optional(),
  credits: KeyCreditsData$outboundSchema.optional(),
  ratelimits: z.array(RatelimitRequest$outboundSchema).optional(),
  enabled: z.boolean().default(true),
  recoverable: z.boolean().default(false),
});

export function v2KeysCreateKeyRequestBodyToJSON(
  v2KeysCreateKeyRequestBody: V2KeysCreateKeyRequestBody,
): string {
  return JSON.stringify(
    V2KeysCreateKeyRequestBody$outboundSchema.parse(v2KeysCreateKeyRequestBody),
  );
}