import * as z from "zod/v3";
import { KeyCreditsData, KeyCreditsData$Outbound } from "./keycreditsdata.js";
import { RatelimitRequest, RatelimitRequest$Outbound } 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 declare const V2KeysCreateKeyRequestBody$outboundSchema: z.ZodType<V2KeysCreateKeyRequestBody$Outbound, z.ZodTypeDef, V2KeysCreateKeyRequestBody>;
export declare function v2KeysCreateKeyRequestBodyToJSON(v2KeysCreateKeyRequestBody: V2KeysCreateKeyRequestBody): string;
//# sourceMappingURL=v2keyscreatekeyrequestbody.d.ts.map