@unkey/api/src/models/components/v2keysverifykeyrequestbody.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 {
  KeysVerifyKeyCredits,
  KeysVerifyKeyCredits$Outbound,
  KeysVerifyKeyCredits$outboundSchema,
} from "./keysverifykeycredits.js";
import {
  KeysVerifyKeyRatelimit,
  KeysVerifyKeyRatelimit$Outbound,
  KeysVerifyKeyRatelimit$outboundSchema,
} from "./keysverifykeyratelimit.js";

export type V2KeysVerifyKeyRequestBody = {
  /**
   * The API key to verify, exactly as provided by your user.
   *
   * @remarks
   * Include any prefix - even small changes will cause verification to fail.
   */
  key: string;
  /**
   * Attaches metadata tags for analytics and monitoring without affecting verification outcomes.
   *
   * @remarks
   * Enables segmentation of API usage in dashboards by endpoint, client version, region, or custom dimensions.
   * Use 'key=value' format for compatibility with most analytics tools and clear categorization.
   * Avoid including sensitive data in tags as they may appear in logs and analytics reports.
   */
  tags?: Array<string> | undefined;
  /**
   * Checks if the key has the specified permission(s) using a query syntax.
   *
   * @remarks
   * Supports single permissions, logical operators (AND, OR), and parentheses for grouping.
   * Examples:
   * - Single permission: "documents.read"
   * - Multiple permissions: "documents.read AND documents.write"
   * - Complex queries: "(documents.read OR documents.write) AND users.view"
   * Verification fails if the key lacks the required permissions through direct assignment or role inheritance.
   */
  permissions?: string | undefined;
  /**
   * Controls credit consumption for usage-based billing and quota enforcement.
   *
   * @remarks
   * Omitting this field uses the default cost of 1 credit per verification.
   * Credits provide globally consistent usage tracking, essential for paid APIs with strict quotas.
   */
  credits?: KeysVerifyKeyCredits | undefined;
  /**
   * Enforces time-based rate limiting during verification to prevent abuse and ensure fair usage.
   *
   * @remarks
   * Omitting this field skips rate limit checks entirely, relying only on configured key rate limits.
   * Multiple rate limits can be checked simultaneously, each with different costs and temporary overrides.
   * Rate limit checks are optimized for performance but may allow brief bursts during high concurrency.
   */
  ratelimits?: Array<KeysVerifyKeyRatelimit> | undefined;
  /**
   * Migrate keys on demand from your previous system. Reach out for migration support at support@unkey.dev
   */
  migrationId?: string | undefined;
};

/** @internal */
export type V2KeysVerifyKeyRequestBody$Outbound = {
  key: string;
  tags?: Array<string> | undefined;
  permissions?: string | undefined;
  credits?: KeysVerifyKeyCredits$Outbound | undefined;
  ratelimits?: Array<KeysVerifyKeyRatelimit$Outbound> | undefined;
  migrationId?: string | undefined;
};

/** @internal */
export const V2KeysVerifyKeyRequestBody$outboundSchema: z.ZodType<
  V2KeysVerifyKeyRequestBody$Outbound,
  z.ZodTypeDef,
  V2KeysVerifyKeyRequestBody
> = z.object({
  key: z.string(),
  tags: z.array(z.string()).optional(),
  permissions: z.string().optional(),
  credits: KeysVerifyKeyCredits$outboundSchema.optional(),
  ratelimits: z.array(KeysVerifyKeyRatelimit$outboundSchema).optional(),
  migrationId: z.string().optional(),
});

export function v2KeysVerifyKeyRequestBodyToJSON(
  v2KeysVerifyKeyRequestBody: V2KeysVerifyKeyRequestBody,
): string {
  return JSON.stringify(
    V2KeysVerifyKeyRequestBody$outboundSchema.parse(v2KeysVerifyKeyRequestBody),
  );
}