components

type BadRequestErrorDetails struct {
	// A human-readable explanation specific to this occurrence of the problem. This provides detailed information about what went wrong and potential remediation steps. The message is intended to be helpful for developers troubleshooting the issue.
	Detail string `json:"detail"`
	// HTTP status code that corresponds to this error. This will match the status code in the HTTP response. Common codes include `400` (Bad Request), `401` (Unauthorized), `403` (Forbidden), `404` (Not Found), `409` (Conflict), and `500` (Internal Server Error).
	Status int64 `json:"status"`
	// A short, human-readable summary of the problem type. This remains constant from occurrence to occurrence of the same problem and should be used for programmatic handling.
	Title string `json:"title"`
	// A URI reference that identifies the problem type. This provides a stable identifier for the error that can be used for documentation lookups and programmatic error handling. When followed, this URI should provide human-readable documentation for the problem type.
	Type string `json:"type"`
	// List of individual validation errors that occurred in the request. Each error provides specific details about what failed validation, where the error occurred in the request, and suggestions for fixing it. This granular information helps developers quickly identify and resolve multiple issues in a single request without having to make repeated API calls.
	Errors []ValidationError `json:"errors"`
}

type BaseError struct {
	// A human-readable explanation specific to this occurrence of the problem. This provides detailed information about what went wrong and potential remediation steps. The message is intended to be helpful for developers troubleshooting the issue.
	Detail string `json:"detail"`
	// HTTP status code that corresponds to this error. This will match the status code in the HTTP response. Common codes include `400` (Bad Request), `401` (Unauthorized), `403` (Forbidden), `404` (Not Found), `409` (Conflict), and `500` (Internal Server Error).
	Status int64 `json:"status"`
	// A short, human-readable summary of the problem type. This remains constant from occurrence to occurrence of the same problem and should be used for programmatic handling.
	Title string `json:"title"`
	// A URI reference that identifies the problem type. This provides a stable identifier for the error that can be used for documentation lookups and programmatic error handling. When followed, this URI should provide human-readable documentation for the problem type.
	Type string `json:"type"`
}

type Code string

type EmptyResponse struct {
}

type HTTPMetadata struct {
	// Raw HTTP response; suitable for custom response parsing
	Response *http.Response `json:"-"`
	// Raw HTTP request; suitable for debugging
	Request *http.Request `json:"-"`
}

type Identity struct {
	// Identity ID
	ID string `json:"id"`
	// External identity ID
	ExternalID string `json:"externalId"`
	// Identity metadata
	Meta map[string]any `json:"meta,omitempty"`
	// Identity ratelimits
	Ratelimits []RatelimitResponse `json:"ratelimits,omitempty"`
}

type KeyCreditsData struct {
	// Number of credits remaining (null for unlimited).
	Remaining *int64 `json:"remaining"`
	// Configuration for automatic credit refill behavior.
	Refill *KeyCreditsRefill `json:"refill,omitempty"`
}

type KeyCreditsRefill struct {
	// How often credits are automatically refilled.
	Interval KeyCreditsRefillInterval `json:"interval"`
	// Number of credits to add during each refill cycle.
	Amount int64 `json:"amount"`
	// Day of the month for monthly refills (1-31).
	// Only required when interval is 'monthly'.
	// For days beyond the month's length, refill occurs on the last day of the month.
	//
	RefillDay *int64 `json:"refillDay,omitempty"`
}

type KeyCreditsRefillInterval string

type KeyResponseData struct {
	// Unique identifier for this key.
	KeyID string `json:"keyId"`
	// First few characters of the key for identification.
	Start string `json:"start"`
	// Whether the key is enabled or disabled.
	Enabled bool `json:"enabled"`
	// Human-readable name for this key.
	Name *string `json:"name,omitempty"`
	// Custom metadata associated with this key.
	Meta map[string]any `json:"meta,omitempty"`
	// Unix timestamp in milliseconds when key was created.
	CreatedAt int64 `json:"createdAt"`
	// Unix timestamp in milliseconds when key was last updated.
	UpdatedAt *int64 `json:"updatedAt,omitempty"`
	// Unix timestamp in milliseconds when key expires (if set).
	Expires     *int64   `json:"expires,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
	Roles       []string `json:"roles,omitempty"`
	// Credit configuration and remaining balance for this key.
	Credits  *KeyCreditsData `json:"credits,omitempty"`
	Identity *Identity       `json:"identity,omitempty"`
	// Decrypted key value (only when decrypt=true).
	Plaintext  *string             `json:"plaintext,omitempty"`
	Ratelimits []RatelimitResponse `json:"ratelimits,omitempty"`
}

type KeysVerifyKeyCredits struct {
	// Sets how many credits to deduct for this verification request.
	// Use 0 for read-only operations or free tier access, higher values for premium features.
	// Credits are deducted after all security checks pass.
	// Essential for implementing usage-based pricing with different operation costs.
	//
	Cost int `json:"cost"`
}

type KeysVerifyKeyRatelimit struct {
	// References an existing ratelimit by its name. Key Ratelimits will take precedence over identifier-based limits.
	Name string `json:"name"`
	// Optionally override how expensive this operation is and how many tokens are deducted from the current limit.
	Cost *int64 `default:"1" json:"cost"`
	// Optionally override the maximum number of requests allowed within the specified interval.
	Limit *int64 `json:"limit,omitempty"`
	// Optionally override the duration of the rate limit window duration.
	Duration *int64 `json:"duration,omitempty"`
}

type Meta struct {
	// A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
	RequestID string `json:"requestId"`
}

type Operation string

type Pagination struct {
	// Opaque pagination token for retrieving the next page of results.
	// Include this exact value in the cursor field of subsequent requests.
	// Cursors are temporary and may expire after extended periods.
	//
	Cursor *string `json:"cursor,omitempty"`
	// Indicates whether additional results exist beyond this page.
	// When true, use the cursor to fetch the next page.
	// When false, you have reached the end of the result set.
	//
	HasMore bool `json:"hasMore"`
}

type Permission struct {
	// The unique identifier for this permission within Unkey's system.
	// Generated automatically when the permission is created and used to reference this permission in API operations.
	// Always begins with 'perm_' followed by alphanumeric characters and underscores.
	//
	ID string `json:"id"`
	// The human-readable name for this permission that describes its purpose.
	// Should be descriptive enough for developers to understand what access it grants.
	// Use clear, semantic names that reflect the resources or actions being permitted.
	// Names must be unique within your workspace to avoid confusion and conflicts.
	//
	Name string `json:"name"`
	// The unique URL-safe identifier for this permission.
	Slug string `json:"slug"`
	// Optional detailed explanation of what this permission grants access to.
	// Helps team members understand the scope and implications of granting this permission.
	// Include information about what resources can be accessed and what actions can be performed.
	// Not visible to end users - this is for internal documentation and team clarity.
	//
	Description *string `json:"description,omitempty"`
}

type RatelimitOverride struct {
	// The unique identifier of this specific rate limit override. This ID is generated when the override is created and can be used for management operations like updating or deleting the override.
	OverrideID string `json:"overrideId"`
	// The duration in milliseconds for this override's rate limit window. This may differ from the default duration for the namespace, allowing custom time windows for specific entities. After this duration elapses, the rate limit counter for affected identifiers resets to zero.
	Duration int64 `json:"duration"`
	// The identifier pattern this override applies to. This determines which entities receive the custom rate limit.
	//
	// This can be:
	// - An exact identifier for a specific entity
	// - A pattern with wildcards for matching multiple entities
	//
	// Wildcard examples:
	// - 'admin_*' matches any identifier starting with 'admin_'
	// - '*_test' matches any identifier ending with '_test'
	// - '*premium*' matches any identifier containing 'premium'
	//
	// More complex patterns can combine multiple wildcards. Detailed documentation on pattern matching rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
	Identifier string `json:"identifier"`
	// The maximum number of requests allowed for entities matching this override. This replaces the default limit for the namespace when applied.
	//
	// Common use cases:
	// - Higher limits for premium customers
	// - Reduced limits for abusive or suspicious entities
	// - Zero limit to completely block specific patterns
	// - Custom tier-based limits for different customer segments
	Limit int64 `json:"limit"`
}

type RatelimitRequest struct {
	// The name of this rate limit. This name is used to identify which limit to check during key verification.
	//
	// Best practices for limit names:
	// - Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads'
	// - Be consistent with naming conventions across your application
	// - Create separate limits for different resource types or operation costs
	// - Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training')
	//
	// You will reference this exact name when verifying keys to check against this specific limit.
	Name string `json:"name"`
	// The maximum number of operations allowed within the specified time window.
	//
	// When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect:
	// - Your infrastructure capacity and scaling limitations
	// - Fair usage expectations for your service
	// - Different tier levels for various user types
	// - The relative cost of the operations being limited
	//
	// Higher values allow more frequent access but may impact service performance.
	Limit int64 `json:"limit"`
	// The duration for each ratelimit window in milliseconds.
	//
	// This controls how long the rate limit counter accumulates before resetting. Common values include:
	// - 1000 (1 second): For strict per-second limits on high-frequency operations
	// - 60000 (1 minute): For moderate API usage control
	// - 3600000 (1 hour): For less frequent but costly operations
	// - 86400000 (24 hours): For daily quotas
	//
	// Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.
	Duration int64 `json:"duration"`
	// Whether this ratelimit should be automatically applied when verifying a key.
	AutoApply *bool `default:"false" json:"autoApply"`
}

type RatelimitResponse struct {
	// Unique identifier for this rate limit configuration.
	ID string `json:"id"`
	// Human-readable name for this rate limit.
	Name string `json:"name"`
	// Maximum requests allowed within the time window.
	Limit int64 `json:"limit"`
	// Rate limit window duration in milliseconds.
	Duration int64 `json:"duration"`
	// Whether this rate limit was automatically applied when verifying the key.
	AutoApply bool `json:"autoApply"`
}

type Role struct {
	// The unique identifier for this role within Unkey's system.
	// Generated automatically when the role is created and used to reference this role in API operations.
	// Always begins with 'role_' followed by alphanumeric characters and underscores.
	//
	ID string `json:"id"`
	// The human-readable name for this role that describes its function.
	// Should be descriptive enough for administrators to understand what access this role provides.
	// Use clear, semantic names that reflect the job function or responsibility level.
	// Names must be unique within your workspace to avoid confusion during role assignment.
	//
	Name string `json:"name"`
	// Optional detailed explanation of what this role encompasses and what access it provides.
	// Helps team members understand the role's scope, intended use cases, and security implications.
	// Include information about what types of users should receive this role and what they can accomplish.
	// Not visible to end users - this is for internal documentation and access control audits.
	//
	Description *string `json:"description,omitempty"`
	// Complete list of permissions currently assigned to this role.
	// Each permission grants specific access rights that will be inherited by any keys or users assigned this role.
	// Use this list to understand the full scope of access provided by this role.
	// Permissions can be added or removed from roles without affecting the role's identity or other properties.
	// Empty array indicates a role with no permissions currently assigned.
	//
	Permissions []Permission `json:"permissions,omitempty"`
}

type Security struct {
	RootKey *string `security:"scheme,type=http,subtype=bearer,name=Authorization,env=unkey_root_key"`
}

type UpdateKeyCreditsData struct {
	// Number of credits remaining (null for unlimited). This also clears the refilling schedule.
	Remaining *int64 `json:"remaining,omitempty"`
	// Configuration for automatic credit refill behavior.
	Refill *UpdateKeyCreditsRefill `json:"refill,omitempty"`
}

type UpdateKeyCreditsRefill struct {
	// How often credits are automatically refilled.
	Interval UpdateKeyCreditsRefillInterval `json:"interval"`
	// Number of credits to add during each refill cycle.
	Amount int64 `json:"amount"`
	// Day of the month for monthly refills (1-31).
	// Only required when interval is 'monthly'.
	// For days beyond the month's length, refill occurs on the last day of the month.
	//
	RefillDay *int64 `json:"refillDay,omitempty"`
}

type UpdateKeyCreditsRefillInterval string

type V2ApisCreateAPIRequestBody struct {
	// Unique identifier for this API namespace within your workspace.
	// Use descriptive names like 'payment-service-prod' or 'user-api-dev' to clearly identify purpose and environment.
	//
	Name string `json:"name"`
}

type V2ApisCreateAPIResponseBody struct {
	// 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 Meta                        `json:"meta"`
	Data V2ApisCreateAPIResponseData `json:"data"`
}

type V2ApisCreateAPIResponseData struct {
	// The unique identifier assigned to the newly created API.
	// Use this ID for all subsequent operations including key creation, verification, and API management.
	// Always begins with 'api_' followed by a unique alphanumeric sequence.
	//
	// Store this ID securely as it's required when:
	// - Creating API keys within this namespace
	// - Verifying keys associated with this API
	// - Managing API settings and metadata
	// - Listing keys belonging to this API
	//
	// This identifier is permanent and cannot be changed after creation.
	//
	APIID string `json:"apiId"`
}

type V2ApisDeleteAPIRequestBody struct {
	// Specifies which API namespace to permanently delete from your workspace.
	// Must be a valid API ID that begins with 'api_' and exists within your workspace.
	//
	// Before proceeding, ensure you have the correct API ID and understand that this action cannot be undone. If you need to migrate functionality, create replacement keys in a new API namespace and update client applications before deletion.
	//
	APIID string `json:"apiId"`
}

type V2ApisDeleteAPIResponseBody struct {
	// 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 Meta `json:"meta"`
	// Empty response object by design. A successful response indicates this operation was successfully executed.
	Data EmptyResponse `json:"data"`
}

type V2ApisGetAPIRequestBody struct {
	// Specifies which API to retrieve by its unique identifier.
	// Must be a valid API ID that begins with 'api_' and exists within your workspace.
	//
	APIID string `json:"apiId"`
}

type V2ApisGetAPIResponseBody struct {
	// 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 Meta                     `json:"meta"`
	Data V2ApisGetAPIResponseData `json:"data"`
}

type V2ApisGetAPIResponseData struct {
	// The unique identifier of this API within Unkey's system.
	// Used in all operations related to this API including key creation, verification, and management.
	// Always begins with 'api_' followed by alphanumeric characters and underscores.
	// This identifier is permanent and never changes after API creation.
	//
	ID string `json:"id"`
	// The internal name of this API as specified during creation.
	// Used for organization and identification within your workspace.
	// Helps distinguish between different environments, services, or access tiers.
	// Not visible to end users - this is purely for administrative purposes.
	//
	Name string `json:"name"`
}

type V2ApisListKeysRequestBody struct {
	// The API namespace whose keys you want to list.
	// Returns all keys in this API, subject to pagination and filters.
	//
	APIID string `json:"apiId"`
	// Maximum number of keys to return per request.
	// Balance between response size and number of pagination calls needed.
	//
	Limit *int64 `default:"100" json:"limit"`
	// Pagination cursor from previous response to fetch next page.
	// Use when `hasMore: true` in previous response.
	//
	Cursor *string `json:"cursor,omitempty"`
	// Filter keys by external ID to find keys for a specific user or entity.
	// Must exactly match the externalId set during key creation.
	//
	ExternalID *string `json:"externalId,omitempty"`
	// When true, attempts to include the plaintext key value in the response. SECURITY WARNING:
	// - This requires special permissions on the calling root key
	// - Only works for keys created with 'recoverable: true'
	// - Exposes sensitive key material in the response
	// - Should only be used in secure administrative contexts
	// - Never enable this in user-facing applications
	Decrypt *bool `default:"false" json:"decrypt"`
	// EXPERIMENTAL: Skip the cache and fetch the keys directly from the database. This ensures you see the most recent state, including keys created moments ago. Use this when:
	// - You've just created a key and need to display it immediately
	// - You need absolute certainty about the current key state
	// - You're debugging cache consistency issues
	//
	// This parameter comes with a performance cost and should be used sparingly.
	RevalidateKeysCache *bool `default:"false" json:"revalidateKeysCache"`
}

type V2ApisListKeysResponseBody struct {
	// 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 Meta `json:"meta"`
	// Array of API keys with complete configuration and metadata.
	Data []KeyResponseData `json:"data"`
	// Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
	Pagination *Pagination `json:"pagination,omitempty"`
}

type V2IdentitiesCreateIdentityRequestBody struct {
	// Creates an identity using your system's unique identifier for a user, organization, or entity.
	// 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 `json:"externalId"`
	// Stores arbitrary JSON metadata returned during key verification for contextual information.
	// 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 map[string]any `json:"meta,omitempty"`
	// Defines shared rate limits that apply to all keys belonging to this identity.
	// 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 []RatelimitRequest `json:"ratelimits,omitempty"`
}

type V2IdentitiesCreateIdentityResponseBody struct {
	// 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 Meta                                   `json:"meta"`
	Data V2IdentitiesCreateIdentityResponseData `json:"data"`
}

type V2IdentitiesCreateIdentityResponseData struct {
	// The unique identifier of the created identity.
	IdentityID string `json:"identityId"`
}

type V2IdentitiesDeleteIdentityRequestBody struct {
	// The ID of the identity to delete. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service).
	Identity string `json:"identity"`
}

type V2IdentitiesDeleteIdentityResponseBody struct {
	// 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 Meta `json:"meta"`
}

type V2IdentitiesGetIdentityRequestBody struct {
	// The ID of the identity to retrieve. This can be either the externalId (from your own system that was used during identity creation) or the identityId (the internal ID returned by the identity service).
	Identity string `json:"identity"`
}

type V2IdentitiesGetIdentityResponseBody struct {
	// 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 Meta     `json:"meta"`
	Data Identity `json:"data"`
}

type V2IdentitiesListIdentitiesRequestBody struct {
	// The maximum number of identities to return in a single request. Use this to control response size and loading performance.
	Limit *int64 `default:"100" json:"limit"`
	// Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the response contains a cursor value.
	Cursor *string `json:"cursor,omitempty"`
}

type V2IdentitiesListIdentitiesResponseBody struct {
	// 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 Meta `json:"meta"`
	// List of identities matching the specified criteria.
	Data []Identity `json:"data"`
	// Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
	Pagination Pagination `json:"pagination"`
}

type V2IdentitiesUpdateIdentityRequestBody struct {
	// The ID of the identity to update. Accepts either the externalId (your system-generated identifier) or the identityId (internal identifier returned by the identity service).
	Identity string `json:"identity"`
	// Replaces all existing metadata with this new metadata object.
	// Omitting this field preserves existing metadata, while providing an empty object clears all metadata.
	// 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 map[string]any `json:"meta,omitempty"`
	// Replaces all existing identity rate limits with this complete list of rate limits.
	// Omitting this field preserves existing rate limits, while providing an empty array removes all rate limits.
	// These limits are shared across all keys belonging to this identity, preventing abuse through multiple keys.
	// Rate limit changes take effect immediately but may take up to 30 seconds to propagate across all regions.
	//
	Ratelimits []RatelimitRequest `json:"ratelimits,omitempty"`
}

type V2IdentitiesUpdateIdentityResponseBody struct {
	Data Identity `json:"data"`
	// 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 Meta `json:"meta"`
}

type V2KeysAddPermissionsRequestBody struct {
	// Specifies which key receives the additional permissions using the database identifier returned from `keys.createKey`.
	// Do not confuse this with the actual API key string that users include in requests.
	//
	KeyID string `json:"keyId"`
	// Grants additional permissions to the key through direct assignment or automatic creation.
	// Duplicate permissions are ignored automatically, making this operation idempotent.
	//
	// Adding permissions never removes existing permissions or role-based permissions.
	//
	// Any permissions that do not exist will be auto created if the root key has permissions, otherwise this operation will fail with a 403 error.
	//
	Permissions []string `json:"permissions"`
}

type V2KeysAddPermissionsResponseBody struct {
	// 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 Meta `json:"meta"`
	// Complete list of all permissions directly assigned to the key (including both newly added permissions and those that were already assigned).
	//
	// This response includes:
	// - All direct permissions assigned to the key (both pre-existing and newly added)
	// - Both the permission ID and name for each permission
	//
	// Important notes:
	// - This list does NOT include permissions granted through roles
	// - For a complete permission picture, use `/v2/keys.getKey` instead
	// - An empty array indicates the key has no direct permissions assigned
	Data []Permission `json:"data"`
}

type V2KeysAddRolesRequestBody struct {
	// Specifies which key receives the additional roles using the database identifier returned from `createKey`.
	// Do not confuse this with the actual API key string that users include in requests.
	// Added roles supplement existing roles and permissions without replacing them.
	// Role assignments take effect immediately but may take up to 30 seconds to propagate across all regions.
	//
	KeyID string `json:"keyId"`
	// Assigns additional roles to the key through direct assignment to existing workspace roles.
	// Operations are idempotent - adding existing roles has no effect and causes no errors.
	//
	// All roles must already exist in the workspace - roles cannot be created automatically.
	// Invalid roles cause the entire operation to fail atomically, ensuring consistent state.
	//
	Roles []string `json:"roles"`
}

type V2KeysAddRolesResponseBody struct {
	// 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 Meta `json:"meta"`
	// Complete list of all roles directly assigned to the key after the operation completes.
	//
	// The response includes:
	// - All roles now assigned to the key (both pre-existing and newly added)
	// - Both ID and name of each role for easy reference
	//
	// Important notes:
	// - The response shows the complete current state after the addition
	// - An empty array means the key has no roles assigned (unlikely after an add operation)
	// - This only shows direct role assignments, not inherited or nested roles
	// - Role permissions are not expanded in this response - use keys.getKey for full details
	Data []Role `json:"data"`
}

type V2KeysCreateKeyRequestBody struct {
	// The API namespace this key belongs to.
	// Keys from different APIs cannot access each other.
	//
	APIID string `json:"apiId"`
	// Adds a visual identifier to the beginning of the generated key for easier recognition in logs and dashboards.
	// 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 `json:"prefix,omitempty"`
	// Sets a human-readable identifier for internal organization and dashboard display.
	// 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 `json:"name,omitempty"`
	// Controls the cryptographic strength of the generated key in bytes.
	// 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 *int64 `default:"16" json:"byteLength"`
	// Links this key to a user or entity in your system using your own identifier.
	// 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 `json:"externalId,omitempty"`
	// Stores arbitrary JSON metadata returned during key verification for contextual information.
	// 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 map[string]any `json:"meta,omitempty"`
	// Assigns existing roles to this key for permission management through role-based access control.
	// 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 []string `json:"roles,omitempty"`
	// Grants specific permissions directly to this key without requiring role membership.
	// 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 []string `json:"permissions,omitempty"`
	// Sets when this key automatically expires as a Unix timestamp in milliseconds.
	// 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 *int64 `json:"expires,omitempty"`
	// Credit configuration and remaining balance for this key.
	Credits *KeyCreditsData `json:"credits,omitempty"`
	// Defines time-based rate limits that protect against abuse by controlling request frequency.
	// 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 []RatelimitRequest `json:"ratelimits,omitempty"`
	// Controls whether the key is active immediately upon creation.
	// 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 *bool `default:"true" json:"enabled"`
	// Controls whether the plaintext key is stored in an encrypted vault for later retrieval.
	// 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 *bool `default:"false" json:"recoverable"`
}

type V2KeysCreateKeyResponseBody struct {
	// 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 Meta                        `json:"meta"`
	Data V2KeysCreateKeyResponseData `json:"data"`
}

type V2KeysCreateKeyResponseData struct {
	// The unique identifier for this key in Unkey's system. This is NOT the actual API key, but a reference ID used for management operations like updating or deleting the key. Store this ID in your database to reference the key later. This ID is not sensitive and can be logged or displayed in dashboards.
	KeyID string `json:"keyId"`
	// The full generated API key that should be securely provided to your user.
	// SECURITY WARNING: This is the only time you'll receive the complete key - Unkey only stores a securely hashed version. Never log or store this value in your own systems; provide it directly to your end user via secure channels. After this API call completes, this value cannot be retrieved again (unless created with `recoverable=true`).
	Key string `json:"key"`
}

type V2KeysDeleteKeyRequestBody struct {
	// Specifies which key to delete using the database identifier returned from `createKey`.
	// Do not confuse this with the actual API key string that users include in requests.
	// Deletion immediately invalidates the key, causing all future verification attempts to fail with `code=NOT_FOUND`.
	// Key deletion triggers cache invalidation across all regions but may take up to 30 seconds to fully propagate.
	//
	KeyID string `json:"keyId"`
	// Controls deletion behavior between recoverable soft-deletion and irreversible permanent erasure.
	// Soft deletion (default) preserves key data for potential recovery through direct database operations.
	// Permanent deletion completely removes all traces including hash values and metadata with no recovery option.
	//
	// Use permanent deletion only for regulatory compliance (GDPR), resolving hash collisions, or when reusing identical key strings.
	// Permanent deletion cannot be undone and may affect analytics data that references the deleted key.
	// Most applications should use soft deletion to maintain audit trails and prevent accidental data loss.
	//
	Permanent *bool `default:"false" json:"permanent"`
}

type V2KeysDeleteKeyResponseBody struct {
	// 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 Meta `json:"meta"`
	// Empty response object by design. A successful response indicates this operation was successfully executed.
	Data EmptyResponse `json:"data"`
}

type V2KeysGetKeyRequestBody struct {
	// Specifies which key to retrieve using the database identifier returned from `keys.createKey`.
	// Do not confuse this with the actual API key string that users include in requests.
	// Key data includes metadata, permissions, usage statistics, and configuration but never the plaintext key value unless `decrypt=true`.
	// Find this ID in creation responses, key listings, dashboard, or verification responses.
	//
	KeyID string `json:"keyId"`
	// Controls whether to include the plaintext key value in the response for recovery purposes.
	// Only works for keys created with `recoverable=true` and requires the `decrypt_key` permission.
	// Returned keys must be handled securely, never logged, cached, or stored insecurely.
	//
	// Use only for legitimate recovery scenarios like user password resets or emergency access.
	// Most applications should keep this false to maintain security best practices and avoid accidental key exposure.
	// Decryption requests are audited and may trigger security alerts in enterprise environments.
	//
	Decrypt *bool `default:"false" json:"decrypt"`
}

type V2KeysGetKeyResponseBody struct {
	// 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 Meta            `json:"meta"`
	Data KeyResponseData `json:"data"`
}

type V2KeysRemovePermissionsRequestBody struct {
	// Specifies which key to remove permissions from using the database identifier returned from `keys.createKey`.
	// Do not confuse this with the actual API key string that users include in requests.
	//
	KeyID string `json:"keyId"`
	// Removes direct permissions from the key without affecting role-based permissions.
	//
	// You can either use a permission slug, or the permission ID.
	//
	// After removal, verification checks for these permissions will fail unless granted through roles.
	//
	Permissions []string `json:"permissions"`
}

type V2KeysRemovePermissionsResponseBody struct {
	// 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 Meta `json:"meta"`
	// Complete list of all permissions directly assigned to the key after the removal operation (remaining permissions only).
	//
	// Notes:
	// - This list does NOT include permissions granted through roles
	// - For a complete permission picture, use `/v2/keys.getKey` instead
	// - An empty array indicates the key has no direct permissions assigned
	// - Any cached versions of the key are immediately invalidated to ensure consistency
	// - Changes to permissions take effect within seconds for new verifications
	Data []Permission `json:"data"`
}

type V2KeysRemoveRolesRequestBody struct {
	// Specifies which key loses the roles using the database identifier returned from createKey.
	// Do not confuse this with the actual API key string that users include in requests.
	// Removing roles only affects direct assignments, not permissions inherited from other sources.
	// Role changes take effect immediately but may take up to 30 seconds to propagate across all regions.
	//
	KeyID string `json:"keyId"`
	// Removes direct role assignments from the key without affecting other role sources or permissions.
	// Operations are idempotent - removing non-assigned roles has no effect and causes no errors.
	//
	// After removal, the key loses access to permissions that were only granted through these roles.
	// Invalid role references cause the entire operation to fail atomically, ensuring consistent state.
	//
	Roles []string `json:"roles"`
}

type V2KeysRemoveRolesResponseBody struct {
	// 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 Meta `json:"meta"`
	// Complete list of all roles directly assigned to the key after the removal operation completes.
	//
	// The response includes:
	// - The remaining roles still assigned to the key (after removing the specified roles)
	// - Both ID and name for each role for easy reference
	//
	// Important notes:
	// - The response reflects the current state after the removal operation
	// - An empty array indicates the key now has no roles assigned
	// - This only shows direct role assignments
	// - Role permissions are not expanded in this response - use keys.getKey for full details
	// - Changes take effect immediately for new verifications but cached sessions may retain old permissions briefly
	Data []Role `json:"data"`
}

type V2KeysRerollKeyRequestBody struct {
	// The database identifier of the key to reroll.
	//
	// This is the unique ID returned when creating or listing keys, NOT the actual API key token.
	// You can find this ID in:
	// - The response from `keys.createKey`
	// - Key verification responses
	// - The Unkey dashboard
	// - API key listing endpoints
	//
	KeyID string `json:"keyId"`
	// Duration in milliseconds until the ORIGINAL key is revoked, starting from now.
	//
	// This parameter controls the overlap period for key rotation:
	// - Set to `0` to revoke the original key immediately
	// - Positive values keep the original key active for the specified duration
	// - Allows graceful migration by giving users time to update their credentials
	//
	// Common overlap periods:
	// - Immediate revocation: 0
	// - 1 hour grace period: 3600000
	// - 24 hours grace period: 86400000
	// - 7 days grace period: 604800000
	// - 30 days grace period: 2592000000
	//
	Expiration int64 `json:"expiration"`
}

type V2KeysRerollKeyResponseBody struct {
	// 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 Meta                        `json:"meta"`
	Data V2KeysRerollKeyResponseData `json:"data"`
}

type V2KeysRerollKeyResponseData struct {
	// The unique identifier for the newly created key.
	//
	// 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 `json:"keyId"`
	// The newly generated API key token (the actual secret that authenticates requests).
	//
	// **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 `json:"key"`
}

type V2KeysSetPermissionsRequestBody struct {
	// Specifies which key receives the additional permissions using the database identifier returned from `keys.createKey`.
	// Do not confuse this with the actual API key string that users include in requests.
	//
	KeyID string `json:"keyId"`
	// The permissions to set for this key.
	//
	// This is a complete replacement operation - it overwrites all existing direct permissions with this new set.
	//
	// Key behaviors:
	// - Providing an empty array removes all direct permissions from the key
	// - This only affects direct permissions - permissions granted through roles are not affected
	// - All existing direct permissions not included in this list will be removed
	//
	// Any permissions that do not exist will be auto created if the root key has permissions, otherwise this operation will fail with a 403 error.
	Permissions []string `json:"permissions"`
}

type V2KeysSetPermissionsResponseBody struct {
	// 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 Meta `json:"meta"`
	// Complete list of all permissions now directly assigned to the key after the set operation has completed.
	//
	// The response includes:
	// - The comprehensive, updated set of direct permissions (reflecting the complete replacement)
	// - Both ID and name for each permission for easy reference
	//
	// Important notes:
	// - This only shows direct permissions, not those granted through roles
	// - An empty array means the key has no direct permissions assigned
	// - For a complete permission picture including roles, use keys.getKey instead
	Data []Permission `json:"data"`
}

type V2KeysSetRolesRequestBody struct {
	// Specifies which key gets the complete role replacement using the database identifier returned from createKey.
	// Do not confuse this with the actual API key string that users include in requests.
	// This is a wholesale replacement operation that removes all existing roles not included in the request.
	// Role changes take effect immediately but may take up to 30 seconds to propagate across all regions.
	//
	KeyID string `json:"keyId"`
	// Replaces all existing role assignments with this complete list of roles.
	// This is a wholesale replacement operation, not an incremental update like add/remove operations.
	//
	// Providing an empty array removes all direct role assignments from the key.
	// All roles must already exist in the workspace - roles cannot be created automatically.
	// Invalid role references cause the entire operation to fail atomically, ensuring consistent state.
	//
	Roles []string `json:"roles"`
}

type V2KeysSetRolesResponseBody struct {
	// 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 Meta `json:"meta"`
	// Complete list of all roles now directly assigned to the key after the set operation has completed.
	//
	// The response includes:
	// - The comprehensive, updated set of roles (reflecting the complete replacement)
	// - Both ID and name for each role for easy reference
	//
	// Important notes:
	// - This response shows the final state after the complete replacement
	// - If you provided an empty array in the request, this will also be empty
	// - This only shows direct role assignments on the key
	// - Role permissions are not expanded in this response - use keys.getKey for complete details
	// - An empty array indicates the key now has no roles assigned at all
	Data []Role `json:"data"`
}

type V2KeysUpdateCreditsRequestBody struct {
	// The ID of the key to update (begins with `key_`). This is the database reference ID for the key, not the actual API key string that users authenticate with. This ID uniquely identifies which key's credits will be updated.
	KeyID string `json:"keyId"`
	// The credit value to use with the specified operation. The meaning depends on the operation: for 'set', this becomes the new remaining credits value; for 'increment', this amount is added to current credits; for 'decrement', this amount is subtracted from current credits.
	//
	// Set to null when using 'set' operation to make the key unlimited (removes usage restrictions entirely). When decrementing, if the result would be negative, remaining credits are automatically set to zero. Credits are consumed during successful key verification, and when credits reach zero, verification fails with `code=INSUFFICIENT_CREDITS`.
	//
	// Required when using 'increment' or 'decrement' operations. Optional for 'set' operation (null creates unlimited usage).
	//
	Value *int64 `json:"value,omitempty"`
	// Defines how to modify the key's remaining credits. Use 'set' to replace current credits with a specific value or unlimited usage, 'increment' to add credits for plan upgrades or credit purchases, and 'decrement' to reduce credits for refunds or policy violations.
	//
	Operation Operation `json:"operation"`
}

type V2KeysUpdateCreditsResponseBody struct {
	// 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 Meta `json:"meta"`
	// Credit configuration and remaining balance for this key.
	Data KeyCreditsData `json:"data"`
}

type V2KeysUpdateKeyRequestBody struct {
	// Specifies which key to update using the database identifier returned from `createKey`.
	// Do not confuse this with the actual API key string that users include in requests.
	//
	KeyID string `json:"keyId"`
	// Sets a human-readable name for internal organization and identification.
	// Omitting this field leaves the current name unchanged, while setting null removes it entirely.
	// Avoid generic names like "API Key" when managing multiple keys per user or service.
	//
	Name *string `json:"name,omitempty"`
	// Links this key to a user or entity in your system for ownership tracking during verification.
	// Omitting this field preserves the current association, while setting null disconnects the key from any identity.
	// Essential for user-specific analytics, billing, and key management across multiple users.
	// Supports letters, numbers, underscores, dots, and hyphens for flexible identifier formats.
	//
	ExternalID *string `json:"externalId,omitempty"`
	// Stores arbitrary JSON metadata returned during key verification.
	// Omitting this field preserves existing metadata, while setting null removes all metadata entirely.
	// 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 map[string]any `json:"meta,omitempty"`
	// Sets when this key automatically expires as a Unix timestamp in milliseconds.
	// Verification fails with code=EXPIRED immediately after this time passes.
	// Omitting this field preserves the current expiration, while setting null makes the key permanent.
	//
	// 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.
	// Active sessions continue until their next verification attempt after expiry.
	//
	Expires *int64 `json:"expires,omitempty"`
	// Credit configuration and remaining balance for this key.
	Credits *UpdateKeyCreditsData `json:"credits,omitempty"`
	// Defines time-based rate limits that protect against abuse by controlling request frequency.
	// Omitting this field preserves existing rate limits, while setting null removes all rate limits.
	// 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.
	//
	Ratelimits []RatelimitRequest `json:"ratelimits,omitempty"`
	// Controls whether the key is currently active for verification requests.
	// When set to `false`, all verification attempts fail with `code=DISABLED` regardless of other settings.
	// Omitting this field preserves the current enabled status.
	// Useful for temporarily suspending access during billing issues, security incidents, or maintenance windows without losing key configuration.
	//
	Enabled     *bool    `json:"enabled,omitempty"`
	Roles       []string `json:"roles,omitempty"`
	Permissions []string `json:"permissions,omitempty"`
}

type V2KeysUpdateKeyResponseBody struct {
	// 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 Meta `json:"meta"`
	// Empty response object by design. A successful response indicates this operation was successfully executed.
	Data EmptyResponse `json:"data"`
}

type V2KeysVerifyKeyRequestBody struct {
	// The API key to verify, exactly as provided by your user.
	// Include any prefix - even small changes will cause verification to fail.
	//
	Key string `json:"key"`
	// Attaches metadata tags for analytics and monitoring without affecting verification outcomes.
	// 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 []string `json:"tags,omitempty"`
	// Checks if the key has the specified permission(s) using a query syntax.
	// 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 `json:"permissions,omitempty"`
	// Controls credit consumption for usage-based billing and quota enforcement.
	// 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 `json:"credits,omitempty"`
	// Enforces time-based rate limiting during verification to prevent abuse and ensure fair usage.
	// 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 []KeysVerifyKeyRatelimit `json:"ratelimits,omitempty"`
}

type V2KeysVerifyKeyResponseBody struct {
	// 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 Meta                        `json:"meta"`
	Data V2KeysVerifyKeyResponseData `json:"data"`
}

type V2KeysVerifyKeyResponseData struct {
	// The primary verification result. If true, the key is valid
	// and can be used. If false, check the 'code' field to understand why verification
	// failed. Your application should always check this field first before proceeding.
	//
	Valid bool `json:"valid"`
	// A machine-readable code indicating the verification status
	// or failure reason. Values: `VALID` (key is valid and passed all checks), `NOT_FOUND` (key doesn't
	// exist or belongs to wrong API), `FORBIDDEN` (key lacks required permissions), `INSUFFICIENT_PERMISSIONS`
	// (key lacks specific required permissions for this request), `INSUFFICIENT_CREDITS`
	// (key has no remaining credits), `USAGE_EXCEEDED` (key exceeded usage limits), `RATE_LIMITED` (key exceeded rate limits), `DISABLED` (key was explicitly disabled),
	// `EXPIRED` (key has passed its expiration date).
	//
	Code Code `json:"code"`
	// The unique identifier of the verified key in Unkey's system.
	// Use this ID for operations like updating or revoking the key. This field
	// is returned for both valid and invalid keys (except when `code=NOT_FOUND`).
	//
	KeyID *string `json:"keyId,omitempty"`
	// The human-readable name assigned to this key during creation.
	// This is useful for displaying in logs or admin interfaces to identify
	// the key's purpose.
	//
	Name *string `json:"name,omitempty"`
	// Custom metadata associated with the key. This can include any
	// JSON-serializable data you stored with the key during creation or updates,
	// such as plan information, feature flags, or user details. Use this to
	// avoid additional database lookups for contextual information needed during
	// API calls.
	//
	Meta map[string]any `json:"meta,omitempty"`
	// Unix timestamp (in milliseconds) when the key will expire.
	// If null or not present, the key has no expiration. You can use this to
	// warn users about upcoming expirations or to understand the validity period.
	//
	Expires *int64 `json:"expires,omitempty"`
	// The number of requests/credits remaining for this key. If null
	// or not present, the key has unlimited usage. This value decreases with
	// each verification (based on the 'cost' parameter) unless explicit credit
	// refills are configured.
	//
	Credits *int `json:"credits,omitempty"`
	// Indicates if the key is currently enabled. Disabled keys will
	// always fail verification with `code=DISABLED`. This is useful for implementing
	// temporary suspensions without deleting the key.
	//
	Enabled *bool `json:"enabled,omitempty"`
	// A list of all permission names assigned to this key, either
	// directly or through roles. These permissions determine what actions the
	// key can perform. Only returned when permissions were checked during verification
	// or when the key fails with `code=FORBIDDEN`.
	//
	Permissions []string `json:"permissions,omitempty"`
	// A list of all role names assigned to this key. Roles are collections
	// of permissions that grant access to specific functionality. Only returned
	// when permissions were checked during verification.
	//
	Roles      []string                 `json:"roles,omitempty"`
	Identity   *Identity                `json:"identity,omitempty"`
	Ratelimits []VerifyKeyRatelimitData `json:"ratelimits,omitempty"`
}

type V2KeysWhoamiRequestBody struct {
	// The complete API key string provided by you, including any prefix.
	// Never log, cache, or store API keys in your system as they provide full access to user resources.
	// Include the full key exactly as provided - even minor modifications will cause a not found error.
	//
	Key string `json:"key"`
}

type V2KeysWhoamiResponseBody struct {
	// 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 Meta            `json:"meta"`
	Data KeyResponseData `json:"data"`
}

type V2PermissionsCreatePermissionRequestBody struct {
	// Creates a permission with this human-readable name that describes its purpose.
	// Names must be unique within your workspace to prevent conflicts during assignment.
	// Use clear, semantic names that developers can easily understand when building authorization logic.
	// Consider using hierarchical naming conventions like 'resource.action' for better organization.
	//
	// Examples: 'users.read', 'billing.write', 'analytics.view', 'admin.manage'
	//
	Name string `json:"name"`
	// Creates a URL-safe identifier for this permission that can be used in APIs and integrations.
	// Must start with a letter and contain only letters, numbers, periods, underscores, and hyphens.
	// Slugs are often used in REST endpoints, configuration files, and external integrations.
	// Should closely match the name but in a format suitable for technical usage.
	// Must be unique within your workspace to ensure reliable permission lookups.
	//
	// Keep slugs concise but descriptive for better developer experience.
	//
	Slug string `json:"slug"`
	// Provides detailed documentation of what this permission grants access to.
	// Include information about affected resources, allowed actions, and any important limitations.
	// This internal documentation helps team members understand permission scope and security implications.
	// Not visible to end users - designed for development teams and security audits.
	//
	// Consider documenting:
	// - What resources can be accessed
	// - What operations are permitted
	// - Any conditions or limitations
	// - Related permissions that might be needed
	//
	Description *string `json:"description,omitempty"`
}

type V2PermissionsCreatePermissionResponseBody struct {
	// 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 Meta                                      `json:"meta"`
	Data V2PermissionsCreatePermissionResponseData `json:"data"`
}

type V2PermissionsCreatePermissionResponseData struct {
	// The unique identifier assigned to the newly created permission.
	// Use this ID to reference the permission in role assignments, key operations, and other API calls.
	// Always begins with 'perm_' followed by a unique alphanumeric sequence.
	// Store this ID if you need to manage or reference this permission in future operations.
	//
	PermissionID string `json:"permissionId"`
}

type V2PermissionsCreateRoleRequestBody struct {
	// The unique name for this role. Must be unique within your workspace and clearly indicate the role's purpose. Use descriptive names like 'admin', 'editor', or 'billing_manager'.
	//
	// Examples: 'admin.billing', 'support.readonly', 'developer.api', 'manager.analytics'
	//
	Name string `json:"name"`
	// Provides comprehensive documentation of what this role encompasses and what access it grants.
	// Include information about the intended use case, what permissions should be assigned, and any important considerations.
	// This internal documentation helps team members understand role boundaries and security implications.
	// Not visible to end users - designed for administration teams and access control audits.
	//
	// Consider documenting:
	// - The role's intended purpose and scope
	// - What types of users should receive this role
	// - What permissions are typically associated with it
	// - Any security considerations or limitations
	// - Related roles that might be used together
	//
	Description *string `json:"description,omitempty"`
}

type V2PermissionsCreateRoleResponseBody struct {
	// 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 Meta                                `json:"meta"`
	Data V2PermissionsCreateRoleResponseData `json:"data"`
}

type V2PermissionsCreateRoleResponseData struct {
	// The unique identifier assigned to the newly created role.
	// Use this ID to reference the role in permission assignments, key operations, and role management calls.
	// Always begins with 'role_' followed by a unique alphanumeric sequence.
	// Store this ID if you need to manage, modify, or assign this role in future operations.
	//
	RoleID string `json:"roleId"`
}

type V2PermissionsDeletePermissionRequestBody struct {
	// Specifies which permission to permanently delete from your workspace.
	//
	// This can be a permission ID or a permission slug.
	//
	// WARNING: Deleting a permission has immediate and irreversible consequences:
	// - All API keys with this permission will lose that access immediately
	// - All roles containing this permission will have it removed
	// - Any verification requests checking for this permission will fail
	// - This action cannot be undone
	//
	// Before deletion, ensure you:
	// - Have updated any keys or roles that depend on this permission
	// - Have migrated to alternative permissions if needed
	// - Have notified affected users about the access changes
	//
	Permission string `json:"permission"`
}

type V2PermissionsDeletePermissionResponseBody struct {
	// 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 Meta `json:"meta"`
	// Empty response object by design. A successful response indicates this operation was successfully executed.
	Data EmptyResponse `json:"data"`
}

type V2PermissionsDeleteRoleRequestBody struct {
	// Unique identifier of the role to permanently delete from your workspace.
	// Must either be a valid role ID that begins with 'role_' or the given role name and exists within your workspace.
	//
	// WARNING: Deletion is immediate and irreversible with significant consequences:
	// - All API keys assigned this role will lose the associated permissions
	// - Access to resources protected by this role's permissions will be denied
	// - Any authorization logic depending on this role will start failing
	// - Historical analytics referencing this role remain intact
	//
	// Before deletion, ensure:
	// - You've updated any dependent authorization logic or code
	// - You've migrated any keys to use alternative roles or direct permissions
	// - You've notified relevant team members of the access changes
	//
	Role string `json:"role"`
}

type V2PermissionsDeleteRoleResponseBody struct {
	// 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 Meta `json:"meta"`
	// Empty response object by design. A successful response indicates this operation was successfully executed.
	Data EmptyResponse `json:"data"`
}

type V2PermissionsGetPermissionRequestBody struct {
	// The unique identifier of the permission to retrieve. Must be a valid permission ID that begins with 'perm_' and exists within your workspace.
	//
	Permission string `json:"permission"`
}

type V2PermissionsGetPermissionResponseBody struct {
	// 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 Meta       `json:"meta"`
	Data Permission `json:"data"`
}

type V2PermissionsGetRoleRequestBody struct {
	// Unique identifier of the role to permanently delete from your workspace.
	// Must either be a valid role ID that begins with 'role_' or the given role name and exists within your workspace.
	//
	// Use this endpoint to verify role details, check its current permissions, or retrieve metadata.
	// Returns complete role information including all assigned permissions for comprehensive access review.
	//
	Role string `json:"role"`
}

type V2PermissionsGetRoleResponseBody struct {
	// 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 Meta `json:"meta"`
	Data Role `json:"data"`
}

type V2PermissionsListPermissionsRequestBody struct {
	// Pagination cursor from a previous response to fetch the next page of permissions.
	// Include this value when you need to retrieve additional permissions beyond the initial response.
	// Each response containing more results than the requested limit includes a cursor for subsequent pages.
	//
	// Leave empty or omit this field to start from the beginning of the permission list.
	// Cursors are temporary and may expire - always handle cases where a cursor becomes invalid.
	//
	Cursor *string `json:"cursor,omitempty"`
	// Maximum number of permissions to return in a single response.
	Limit *int64 `default:"100" json:"limit"`
}

type V2PermissionsListPermissionsResponseBody struct {
	// 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 Meta `json:"meta"`
	// Array of permission objects with complete configuration details.
	Data []Permission `json:"data"`
	// Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
	Pagination *Pagination `json:"pagination,omitempty"`
}

type V2PermissionsListRolesRequestBody struct {
	// Maximum number of roles to return in a single response.
	// Use smaller values for faster response times and better UI performance.
	// Use larger values when you need to process many roles efficiently.
	// Results exceeding this limit will be paginated with a cursor for continuation.
	//
	Limit *int64 `default:"100" json:"limit"`
	// Pagination cursor from a previous response to fetch the next page of roles.
	// Include this when you need to retrieve additional roles beyond the first page.
	// Each response containing more results will include a cursor value that can be used here.
	// Leave empty or omit this field to start from the beginning of the role list.
	//
	Cursor *string `json:"cursor,omitempty"`
}

type V2PermissionsListRolesResponseBody struct {
	// 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 Meta `json:"meta"`
	// Array of roles with their assigned permissions.
	Data []Role `json:"data"`
	// Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
	Pagination *Pagination `json:"pagination,omitempty"`
}

type V2RatelimitDeleteOverrideRequestBody struct {
	// The id or name of the namespace containing the override.
	Namespace string `json:"namespace"`
	// The exact identifier pattern of the override to delete. This must match exactly as it was specified when creating the override.
	//
	// Important notes:
	// - This is case-sensitive and must match exactly
	// - Include any wildcards (*) that were part of the original pattern
	// - For example, if the override was created for 'premium_*', you must use 'premium_*' here, not a specific ID
	//
	// After deletion, any identifiers previously affected by this override will immediately revert to using the default rate limit for the namespace.
	Identifier string `json:"identifier"`
}

type V2RatelimitDeleteOverrideResponseBody struct {
	// 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 Meta `json:"meta"`
	// Empty response object. A successful response indicates the override was successfully deleted. The operation is immediate - as soon as this response is received, the override no longer exists and affected identifiers have reverted to using the default rate limit for the namespace. No other data is returned as part of the deletion operation.
	Data V2RatelimitDeleteOverrideResponseData `json:"data"`
}

type V2RatelimitDeleteOverrideResponseData struct {
}

type V2RatelimitGetOverrideRequestBody struct {
	// The id or name of the namespace containing the override.
	Namespace string `json:"namespace"`
	// The exact identifier pattern for the override you want to retrieve. This must match exactly as it was specified when creating the override.
	//
	// Important notes:
	// - This is case-sensitive and must match exactly
	// - Include any wildcards (*) that were part of the original pattern
	// - For example, if the override was created for 'premium_*', you must use 'premium_*' here, not a specific ID like 'premium_user1'
	//
	// This field is used to look up the specific override configuration for this pattern.
	Identifier string `json:"identifier"`
}

type V2RatelimitGetOverrideResponseBody struct {
	// 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 Meta              `json:"meta"`
	Data RatelimitOverride `json:"data"`
}

type V2RatelimitLimitRequestBody struct {
	// The id or name of the namespace.
	Namespace string `json:"namespace"`
	// Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.
	// Use higher values for resource-intensive operations and 0 for tracking without limiting.
	// When accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.
	// Essential for implementing fair usage policies and preventing resource abuse through expensive operations.
	//
	Cost *int64 `default:"1" json:"cost"`
	// Sets the rate limit window duration in milliseconds after which the counter resets.
	// Shorter durations enable faster recovery but may be less effective against sustained abuse.
	// Common values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).
	// Balance user experience with protection needs when choosing window sizes.
	//
	Duration int64 `json:"duration"`
	// Defines the scope of rate limiting by identifying the entity being limited.
	// Use user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.
	// Accepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.
	// The same identifier can be used across different namespaces to apply multiple rate limit types.
	// Choose identifiers that provide appropriate granularity for your rate limiting strategy.
	//
	Identifier string `json:"identifier"`
	// Sets the maximum operations allowed within the duration window before requests are rejected.
	// When this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.
	// Balance user experience with resource protection when setting limits for different user tiers.
	// Consider system capacity, business requirements, and fair usage policies in limit determination.
	//
	Limit int64 `json:"limit"`
}

type V2RatelimitLimitResponseBody struct {
	// 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 Meta                         `json:"meta"`
	Data V2RatelimitLimitResponseData `json:"data"`
}

type V2RatelimitLimitResponseData struct {
	// The maximum number of operations allowed within the time window. This reflects either the default limit specified in the request or an override limit if one exists for this identifier.
	//
	// This value helps clients understand their total quota for the current window.
	Limit int64 `json:"limit"`
	// The number of operations remaining in the current window before the rate limit is exceeded. Applications should use this value to:
	//
	// - Implement client-side throttling before hitting limits
	// - Display usage information to end users
	// - Trigger alerts when approaching limits
	// - Adjust request patterns based on available capacity
	//
	// When this reaches zero, requests will be rejected until the window resets.
	Remaining int64 `json:"remaining"`
	// The Unix timestamp in milliseconds when the rate limit window will reset and 'remaining' will return to 'limit'.
	//
	// This timestamp enables clients to:
	// - Calculate and display wait times to users
	// - Implement intelligent retry mechanisms
	// - Schedule requests to resume after the reset
	// - Implement exponential backoff when needed
	//
	// The reset time is based on a sliding window from the first request in the current window.
	Reset int64 `json:"reset"`
	// Whether the request passed the rate limit check. If true, the request is allowed to proceed. If false, the request has exceeded the rate limit and should be blocked or rejected.
	//
	// You MUST check this field to determine if the request should proceed, as the endpoint always returns `HTTP 200` even when rate limited.
	Success bool `json:"success"`
	// If a rate limit override was applied for this identifier, this field contains the ID of the override that was used. Empty when no override is in effect.
	//
	// This can be useful for:
	// - Debugging which override rule was matched
	// - Tracking the effects of specific overrides
	// - Understanding why limits differ from default values
	OverrideID *string `json:"overrideId,omitempty"`
}

type V2RatelimitListOverridesRequestBody struct {
	// The id or name of the rate limit namespace to list overrides for.
	Namespace string `json:"namespace"`
	// Pagination cursor from a previous response. Include this when fetching subsequent pages of results. Each response containing more results than the requested limit will include a cursor value in the pagination object that can be used here.
	Cursor *string `json:"cursor,omitempty"`
	// Maximum number of override entries to return in a single response. Use this to control response size and loading performance.
	//
	// - Lower values (10-20): Better for UI displays and faster response times
	// - Higher values (50-100): Better for data exports or bulk operations
	// - Default (10): Suitable for most dashboard views
	//
	// Results exceeding this limit will be paginated, with a cursor provided for fetching subsequent pages.
	Limit *int64 `default:"10" json:"limit"`
}

type V2RatelimitListOverridesResponseBody struct {
	// 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 Meta                `json:"meta"`
	Data []RatelimitOverride `json:"data"`
	// Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
	Pagination *Pagination `json:"pagination,omitempty"`
}

type V2RatelimitSetOverrideRequestBody struct {
	// The ID or name of the rate limit namespace.
	Namespace string `json:"namespace"`
	// The duration in milliseconds for the rate limit window. This defines how long the rate limit counter accumulates before resetting to zero.
	//
	// Considerations:
	// - This can differ from the default duration for the namespace
	// - Longer durations create stricter limits that take longer to reset
	// - Shorter durations allow more frequent bursts of activity
	// - Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day)
	Duration int64 `json:"duration"`
	// Identifier of the entity receiving this custom rate limit. This can be:
	//
	// - A specific user ID for individual custom limits
	// - An IP address for location-based rules
	// - An email domain for organization-wide policies
	// - Any other string that identifies the target entity
	//
	// Wildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:
	// - 'premium_*' would match all identifiers starting with 'premium_'
	// - '*_admin' would match all identifiers ending with '_admin'
	// - '*suspicious*' would match any identifier containing 'suspicious'
	//
	// More detailed information on wildcard pattern rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
	Identifier string `json:"identifier"`
	// The maximum number of requests allowed for this override. This defines the custom quota for the specified identifier(s).
	//
	// Special values:
	// - Higher than default: For premium or trusted entities
	// - Lower than default: For suspicious or abusive entities
	// - 0: To completely block access (useful for ban implementation)
	//
	// This limit entirely replaces the default limit for matching identifiers.
	Limit int64 `json:"limit"`
}

type V2RatelimitSetOverrideResponseBody struct {
	// 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 Meta                               `json:"meta"`
	Data V2RatelimitSetOverrideResponseData `json:"data"`
}

type V2RatelimitSetOverrideResponseData struct {
	// The unique identifier for the newly created or updated rate limit override. This ID can be used to:
	//
	// - Reference this specific override in subsequent API calls
	// - Delete or modify this override later
	// - Track which override is being applied in rate limit responses
	// - Associate override effects with specific rules in analytics
	//
	// Store this ID if you need to manage the override in the future.
	OverrideID string `json:"overrideId"`
}

type ValidationError struct {
	// JSON path indicating exactly where in the request the error occurred. This helps pinpoint the problematic field or parameter. Examples include:
	// - 'body.name' (field in request body)
	// - 'body.items[3].tags' (nested array element)
	// - 'path.apiId' (path parameter)
	// - 'query.limit' (query parameter)
	// Use this location to identify exactly which part of your request needs correction.
	Location string `json:"location"`
	// Detailed error message explaining what validation rule was violated. This provides specific information about why the field or parameter was rejected, such as format errors, invalid values, or constraint violations.
	Message string `json:"message"`
	// A human-readable suggestion describing how to fix the error. This provides practical guidance on what changes would satisfy the validation requirements. Not all validation errors include fix suggestions, but when present, they offer specific remediation advice.
	Fix *string `json:"fix,omitempty"`
}

type VerifyKeyRatelimitData struct {
	// Whether the rate limit was exceeded.
	Exceeded bool `json:"exceeded"`
	// Unique identifier for this rate limit configuration.
	ID string `json:"id"`
	// Human-readable name for this rate limit.
	Name string `json:"name"`
	// Maximum requests allowed within the time window.
	Limit int64 `json:"limit"`
	// Rate limit window duration in milliseconds.
	Duration int64 `json:"duration"`
	// Rate limit reset duration in milliseconds.
	Reset int64 `json:"reset"`
	// Rate limit remaining requests within the time window.
	Remaining int64 `json:"remaining"`
	// Whether this rate limit should be automatically applied when verifying keys.
	// When true, we will automatically apply this limit during verification without it being explicitly listed.
	//
	AutoApply bool `json:"autoApply"`
}