@unkey/api/src/models/components/v2identitiescreateidentityrequestbody.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 {
  RatelimitRequest,
  RatelimitRequest$Outbound,
  RatelimitRequest$outboundSchema,
} from "./ratelimitrequest.js";

export type V2IdentitiesCreateIdentityRequestBody = {
  /**
   * Creates an identity using your system's unique identifier for a user, organization, or entity.
   *
   * @remarks
   * Must be stable and unique across your workspace - duplicate externalIds return CONFLICT errors.
   * This identifier links Unkey identities to your authentication system, database records, or tenant structure.
   *
   * Avoid changing externalIds after creation as this breaks the link between your systems.
   * Use consistent identifier patterns across your application for easier management and debugging.
   * Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
   * Essential for implementing proper multi-tenant isolation and user-specific rate limiting.
   */
  externalId: string;
  /**
   * 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.
   * Use this for subscription details, feature flags, user preferences, and organization information.
   * Metadata is returned as-is whenever keys associated with this identity are verified.
   */
  meta?: { [k: string]: any } | undefined;
  /**
   * Defines shared rate limits that apply to all keys belonging to this identity.
   *
   * @remarks
   * Prevents abuse by users with multiple keys by enforcing consistent limits across their entire key portfolio.
   * Essential for implementing fair usage policies and tiered access levels in multi-tenant applications.
   *
   * Rate limit counters are shared across all keys with this identity, regardless of how many keys the user creates.
   * During verification, specify which named limits to check for enforcement.
   * Identity rate limits supplement any key-specific rate limits that may also be configured.
   * - Each named limit can have different thresholds and windows
   *
   * When verifying keys, you can specify which limits you want to use and all keys attached to this identity will share the limits, regardless of which specific key is used.
   */
  ratelimits?: Array<RatelimitRequest> | undefined;
};

/** @internal */
export type V2IdentitiesCreateIdentityRequestBody$Outbound = {
  externalId: string;
  meta?: { [k: string]: any } | undefined;
  ratelimits?: Array<RatelimitRequest$Outbound> | undefined;
};

/** @internal */
export const V2IdentitiesCreateIdentityRequestBody$outboundSchema: z.ZodType<
  V2IdentitiesCreateIdentityRequestBody$Outbound,
  z.ZodTypeDef,
  V2IdentitiesCreateIdentityRequestBody
> = z.object({
  externalId: z.string(),
  meta: z.record(z.any()).optional(),
  ratelimits: z.array(RatelimitRequest$outboundSchema).optional(),
});

export function v2IdentitiesCreateIdentityRequestBodyToJSON(
  v2IdentitiesCreateIdentityRequestBody: V2IdentitiesCreateIdentityRequestBody,
): string {
  return JSON.stringify(
    V2IdentitiesCreateIdentityRequestBody$outboundSchema.parse(
      v2IdentitiesCreateIdentityRequestBody,
    ),
  );
}