Migrate pre-hashed API keys from an existing provider into Unkey
Migrate pre-hashed API keys from an existing provider into Unkey.Use this to move keys from another system without requiring users to rotate their credentials. You provide the already-hashed keys and Unkey stores them directly, so existing API keys continue to work after migration. The endpoint returns HTTP 200 even on partial success; hashes that could not be migrated are listed in the response.Important: You must obtain a migrationId from Unkey support before using this command. Keys that already exist in the system will appear in the failed array rather than causing the entire request to fail.Required permissions:Your root key must have one of the following permissions:
api.*.create_key (to migrate keys to any API)
api.<api_id>.create_key (to migrate keys to a specific API)
See the API reference for the full HTTP endpoint documentation.
Identifier of the configured migration provider/strategy to use (e.g., “your_company”). You will receive this from Unkey’s support staff. Must be 3-255 characters.
Sets a human-readable identifier for internal organization and dashboard display. Never exposed to end users, only visible in management interfaces and API responses. Must be 1-255 characters.
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. Must be 1-255 characters.
Stores arbitrary JSON metadata returned during key verification for contextual information. Eliminates additional database lookups during verification. Avoid storing sensitive data here as it is returned in verification responses.
Assigns existing roles to this key for permission management through role-based access control. Roles must already exist in your workspace before assignment.
Grants specific permissions directly to this key without requiring role membership. Wildcard permissions like documents.* grant access to all sub-permissions. Direct permissions supplement any permissions inherited from assigned roles.
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.
Controls whether the key is active immediately upon migration. When set to false, the key exists but all verification attempts fail with code=DISABLED.
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.
Defines time-based rate limits that control request frequency. Multiple rate limits can control different operation types with separate thresholds and windows.
