@unkey/api/dist/commonjs/sdk/keys.d.ts

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

import { ClientSDK, RequestOptions } from "../lib/sdks.js";
import * as components from "../models/components/index.js";
export declare class Keys extends ClientSDK {
    /**
     * Add key permissions
     *
     * @remarks
     * Add permissions to a key without affecting existing permissions.
     *
     * Use this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions granted through roles remain unchanged.
     *
     * **Important**: Changes take effect immediately with up to 30-second edge propagation.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * Invalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds across all regions.
     */
    addPermissions(request: components.V2KeysAddPermissionsRequestBody, options?: RequestOptions): Promise<components.V2KeysAddPermissionsResponseBody>;
    /**
     * Add key roles
     *
     * @remarks
     * Add roles to a key without affecting existing roles or permissions.
     *
     * Use this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based capabilities. Direct permissions remain unchanged.
     *
     * **Important**: Changes take effect immediately with up to 30-second edge propagation.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * Invalidates the key cache for immediate effect, and makes role assignments available for verification within 30 seconds across all regions.
     */
    addRoles(request: components.V2KeysAddRolesRequestBody, options?: RequestOptions): Promise<components.V2KeysAddRolesResponseBody>;
    /**
     * Create API key
     *
     * @remarks
     * Create a new API key for user authentication and authorization.
     *
     * Use this endpoint when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically secure and unique to the specified API namespace.
     *
     * **Important**: The key is returned only once. Store it immediately and provide it to your user, as it cannot be retrieved later.
     *
     * **Common use cases:**
     * - Generate keys for new user registrations
     * - Create additional keys for different applications
     * - Issue keys with specific permissions or limits
     *
     * **Required Permissions**
     *
     * Your root key needs one of:
     * - `api.*.create_key` (create keys in any API)
     * - `api.<api_id>.create_key` (create keys in specific API)
     */
    createKey(request: components.V2KeysCreateKeyRequestBody, options?: RequestOptions): Promise<components.V2KeysCreateKeyResponseBody>;
    /**
     * Delete API keys
     *
     * @remarks
     * Delete API keys permanently from user accounts or for cleanup purposes.
     *
     * Use this for user-requested key deletion, account deletion workflows, or cleaning up unused keys. Keys are immediately invalidated. Two modes: soft delete (default, preserves audit records) and permanent delete.
     *
     * **Important**: For temporary access control, use `updateKey` with `enabled: false` instead of deletion.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.delete_key` (to delete keys in any API)
     * - `api.<api_id>.delete_key` (to delete keys in a specific API)
     */
    deleteKey(request: components.V2KeysDeleteKeyRequestBody, options?: RequestOptions): Promise<components.V2KeysDeleteKeyResponseBody>;
    /**
     * Get API key
     *
     * @remarks
     * Retrieve detailed key information for dashboard interfaces and administrative purposes.
     *
     * Use this to build key management dashboards showing users their key details, status, permissions, and usage data. You can identify keys by `keyId` or the actual key string.
     *
     * **Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions for basic key information:
     * - `api.*.read_key` (to read keys from any API)
     * - `api.<api_id>.read_key` (to read keys from a specific API)
     *
     * Additional permission required for decrypt functionality:
     * - `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
     */
    getKey(request: components.V2KeysGetKeyRequestBody, options?: RequestOptions): Promise<components.V2KeysGetKeyResponseBody>;
    /**
     * Migrate API key(s)
     *
     * @remarks
     * Returns HTTP 200 even on partial success; hashes that could not be migrated are listed under `data.failed`.
     *
     * **Required Permissions**
     * Your root key must have one of the following permissions for basic key information:
     * - `api.*.create_key` (to migrate keys to any API)
     * - `api.<api_id>.create_key` (to migrate keys to a specific API)
     */
    migrateKeys(request: components.V2KeysMigrateKeysRequestBody, options?: RequestOptions): Promise<components.V2KeysMigrateKeysResponseBody>;
    /**
     * Remove key permissions
     *
     * @remarks
     * Remove permissions from a key without affecting existing roles or other permissions.
     *
     * Use this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions granted through roles remain unchanged.
     *
     * **Important**: Changes take effect immediately with up to 30-second edge propagation.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
     */
    removePermissions(request: components.V2KeysRemovePermissionsRequestBody, options?: RequestOptions): Promise<components.V2KeysRemovePermissionsResponseBody>;
    /**
     * Remove key roles
     *
     * @remarks
     * Remove roles from a key without affecting direct permissions or other roles.
     *
     * Use this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based capabilities. Direct permissions remain unchanged.
     *
     * **Important**: Changes take effect immediately with up to 30-second edge propagation.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
     */
    removeRoles(request: components.V2KeysRemoveRolesRequestBody, options?: RequestOptions): Promise<components.V2KeysRemoveRolesResponseBody>;
    /**
     * Reroll Key
     *
     * @remarks
     * Generate a new API key while preserving the configuration from an existing key.
     *
     * This operation creates a fresh key with a new token while maintaining all settings from the original key:
     * - Permissions and roles
     * - Custom metadata
     * - Rate limit configurations
     * - Identity associations
     * - Remaining credits
     * - Recovery settings
     *
     * **Key Generation:**
     * - The system attempts to extract the prefix from the original key
     * - If prefix extraction fails, the default API prefix is used
     * - Key length follows the API's default byte configuration (or 16 bytes if not specified)
     *
     * **Original Key Handling:**
     * - The original key will be revoked after the duration specified in `expiration`
     * - Set `expiration` to 0 to revoke immediately
     * - This allows for graceful key rotation with an overlap period
     *
     * Common use cases include:
     * - Rotating keys for security compliance
     * - Issuing replacement keys for compromised credentials
     * - Creating backup keys with identical permissions
     *
     * **Important:** Analytics and usage metrics are tracked at both the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you to track usage across both individual keys and the overall identity.
     *
     * **Required Permissions**
     *
     *  Your root key must have:
     *  - `api.*.create_key` or `api.<api_id>.create_key`
     *  - `api.*.encrypt_key` or `api.<api_id>.encrypt_key` (only when the original key is recoverable)
     */
    rerollKey(request: components.V2KeysRerollKeyRequestBody, options?: RequestOptions): Promise<components.V2KeysRerollKeyResponseBody>;
    /**
     * Set key permissions
     *
     * @remarks
     * Replace all permissions on a key with the specified set in a single atomic operation.
     *
     * Use this to synchronize with external systems, reset permissions to a known state, or apply standardized permission templates. Permissions granted through roles remain unchanged.
     *
     * **Important**: Changes take effect immediately with up to 30-second edge propagation.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
     */
    setPermissions(request: components.V2KeysSetPermissionsRequestBody, options?: RequestOptions): Promise<components.V2KeysSetPermissionsResponseBody>;
    /**
     * Set key roles
     *
     * @remarks
     * Replace all roles on a key with the specified set in a single atomic operation.
     *
     * Use this to synchronize with external systems, reset roles to a known state, or apply standardized role templates. Direct permissions are never affected.
     *
     * **Important**: Changes take effect immediately with up to 30-second edge propagation.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
     */
    setRoles(request: components.V2KeysSetRolesRequestBody, options?: RequestOptions): Promise<components.V2KeysSetRolesResponseBody>;
    /**
     * Update key credits
     *
     * @remarks
     * Update credit quotas in response to plan changes, billing cycles, or usage purchases.
     *
     * Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage.
     *
     * **Important**: Setting unlimited credits automatically clears existing refill configurations.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * Credit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions.
     */
    updateCredits(request: components.V2KeysUpdateCreditsRequestBody, options?: RequestOptions): Promise<components.V2KeysUpdateCreditsResponseBody>;
    /**
     * Update key settings
     *
     * @remarks
     * Update key properties in response to plan changes, subscription updates, or account status changes.
     *
     * Use this for user upgrades/downgrades, role modifications, or administrative changes. Supports partial updates - only specify fields you want to change. Set fields to null to clear them.
     *
     * **Important**: Permissions and roles are replaced entirely. Use dedicated add/remove endpoints for incremental changes.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions:
     * - `api.*.update_key` (to update keys in any API)
     * - `api.<api_id>.update_key` (to update keys in a specific API)
     *
     * **Side Effects**
     *
     * If you specify an `externalId` that doesn't exist, a new identity will be automatically created and linked to the key. Permission updates will auto-create any permissions that don't exist in your workspace. Changes take effect immediately but may take up to 30 seconds to propagate to all edge regions due to cache invalidation.
     */
    updateKey(request: components.V2KeysUpdateKeyRequestBody, options?: RequestOptions): Promise<components.V2KeysUpdateKeyResponseBody>;
    /**
     * Verify API key
     *
     * @remarks
     * Verify an API key's validity and permissions for request authentication.
     *
     * Use this endpoint on every incoming request to your protected resources. It checks key validity, permissions, rate limits, and usage quotas in a single call.
     *
     * **Important**: Returns HTTP 200 for all verification outcomes — check the `valid` field in response data to determine if the key is authorized. A 429 may be returned if the workspace exceeds its API rate limit.
     *
     * **Common use cases:**
     * - Authenticate API requests before processing
     * - Enforce permission-based access control
     * - Track usage and apply rate limits
     *
     * **Required Permissions**
     *
     * Your root key needs one of:
     * - `api.*.verify_key` (verify keys in any API)
     * - `api.<api_id>.verify_key` (verify keys in specific API)
     *
     * **Note**: If your root key has no verify permissions at all, you will receive a `403 Forbidden` error. If your root key has verify permissions for a different API than the key you're verifying, you will receive a `200` response with `code: NOT_FOUND` to avoid leaking key existence.
     */
    verifyKey(request: components.V2KeysVerifyKeyRequestBody, options?: RequestOptions): Promise<components.V2KeysVerifyKeyResponseBody>;
    /**
     * Get API key by hash
     *
     * @remarks
     * Find out what key this is.
     *
     * **Required Permissions**
     *
     * Your root key must have one of the following permissions for basic key information:
     * - `api.*.read_key` (to read keys from any API)
     * - `api.<api_id>.read_key` (to read keys from a specific API)
     *
     * If your rootkey lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existance of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your root key has the correct permissions.
     */
    whoami(request: components.V2KeysWhoamiRequestBody, options?: RequestOptions): Promise<components.V2KeysWhoamiResponseBody>;
}
//# sourceMappingURL=keys.d.ts.map