Migrate keys to Unkey

This guide walks you through migrating existing API keys to Unkey using the migrate keys endpoint.

Prerequisites#

Create an Unkey account

Create a workspace and keyspace

Note your workspaceId and apiId: - Workspace ID: Settings → General (upper right corner)

API ID: Keyspaces → Your keyspace (upper right corner)

Create a root key

Go to Settings → Root Keys and create one with the api.*.create_key permission, or api.<api_id>.create_key to scope it to the keyspace you are migrating into. If you also plan to verify keys through the API afterwards, add api.*.verify_key.

Get a migration ID

Email support@unkey.com with: - Your workspace ID - Source system (PostgreSQL, Auth0, etc.) - Hash algorithm and key format used We'll set up a migration for your workspace and send you a migrationId.

Hash format#

Unkey never stores plaintext keys. During migration you send the hash of each key, and the hash format is part of the migration we configure for you. When we send you your migrationId, we'll confirm exactly what to submit as the hash value.

The most common setup is SHA-256 of the full key, base64 encoded, which is Unkey's native format. Structured key formats from other providers (for example prefixed keys where only a token segment is hashed) are also supported.

Note

Using a different hash algorithm or key format? Mention it when you contact us and we'll set up your migration accordingly.

Export your keys#

Extract key hashes from your current system. Never include plaintext keys.

Example: PostgreSQL#

SELECT  key_hash,  user_id,  created_at,  metadataFROM api_keysWHERE revoked = false;

Example: MongoDB#

db.apiKeys.find({ revoked: false }, { hash: 1, userId: 1, metadata: 1 });

Hash your keys (if not already hashed)#

If you have plaintext keys, hash them before migration. For a standard SHA-256 migration:

const { createHash } = require("node:crypto");function hashKey(plaintext) {  return createHash("sha256").update(plaintext).digest("base64");}

Migrate to Unkey#

Use the migration API to import your keys:

const UNKEY_ROOT_KEY = process.env.UNKEY_ROOT_KEY;const MIGRATION_ID = "mig_acme"; // From supportconst API_ID = "api_...";// Your exported keysconst keysToMigrate = [  {    hash: "c4fbfe7c69a067cb0841dea343346a750a69908a08ea9656d2a8c19fb0823c64",    externalId: "user_123", // Link to your user    meta: {      plan: "pro",      migratedFrom: "legacy-system",    },    ratelimits: [      {        name: "requests",        limit: 1000,        duration: 60000,        autoApply: true,      },    ],  },  // ... more keys];const response = await fetch("https://api.unkey.com/v2/keys.migrateKeys", {  method: "POST",  headers: {    "Content-Type": "application/json",    Authorization: `Bearer ${UNKEY_ROOT_KEY}`,  },  body: JSON.stringify({    migrationId: MIGRATION_ID,    apiId: API_ID,    keys: keysToMigrate,  }),});const result = await response.json();if (!response.ok) {  console.error(    "Migration failed:",    result?.error || `HTTP ${response.status}`,  );  return;}if (!result?.data) {  console.error("Migration response missing data");  return;}console.log("Migrated:", result.data.migrated.length);console.log("Failed:", result.data.failed.length);

Response#

The endpoint returns HTTP 200 even on partial success. Each migrated key comes back with its hash and the generated keyId, which you should store to manage the key later. Hashes that could not be migrated, for example because a key with that hash already exists, are listed as plain strings under failed:

{  "meta": { "requestId": "req_..." },  "data": {    "migrated": [      {        "hash": "c4fbfe7c69a067cb0841dea343346a750a69908a08ea9656d2a8c19fb0823c64",        "keyId": "key_..."      }    ],    "failed": ["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]  }}

Key configuration options#

Only hash is required for each key. It is the hash string in the format agreed for your migration.

Everything else is optional and works the same as when creating keys: name for internal display, externalId to link the key to a user or entity in your system, meta for arbitrary JSON returned during verification, roles and permissions for access control, ratelimits and credits for usage control, expires as a Unix timestamp in milliseconds, and enabled to control whether the key is active (defaults to true).

See the API reference for the full schema of each field.

Batch migrations#

For large migrations, batch your requests:

const BATCH_SIZE = 100;async function migrateAll(allKeys) {  const results = { migrated: 0, failed: 0 };  for (let i = 0; i < allKeys.length; i += BATCH_SIZE) {    const batch = allKeys.slice(i, i + BATCH_SIZE);    const response = await fetch("https://api.unkey.com/v2/keys.migrateKeys", {      method: "POST",      headers: {        "Content-Type": "application/json",        Authorization: `Bearer ${UNKEY_ROOT_KEY}`,      },      body: JSON.stringify({        migrationId: MIGRATION_ID,        apiId: API_ID,        keys: batch,      }),    });    const result = await response.json();    const batchNum = Math.floor(i / BATCH_SIZE) + 1;    if (!response.ok) {      console.error(        `Batch ${batchNum} failed:`,        result?.error || `HTTP ${response.status}`,      );      results.failed += batch.length;      continue;    }    if (!result?.data) {      console.error(`Batch ${batchNum} missing data`);      results.failed += batch.length;      continue;    }    results.migrated += result.data.migrated.length;    results.failed += result.data.failed.length;    console.log(`Batch ${batchNum}: ${result.data.migrated.length} migrated`);  }  return results;}

Update your verification#

After migration, update your API to verify keys with Unkey. Include your migrationId in each verify key request during the rollout:

// Before: Custom verificationconst isValid = await myDatabase.verifyKey(apiKey);// After: Unkey verificationconst response = await fetch("https://api.unkey.com/v2/keys.verifyKey", {  method: "POST",  headers: {    "Content-Type": "application/json",    Authorization: "Bearer " + process.env.UNKEY_ROOT_KEY,  },  body: JSON.stringify({ key: apiKey, migrationId: MIGRATION_ID }),});const result = await response.json();if (!response.ok || !result?.data) {  // Handle error appropriately  return { valid: false, error: result?.error || "Verification failed" };}const isValid = result.data.valid;

The migrationId lets Unkey match the key against your previous format and transparently convert it to Unkey's native hash on first verification. Once every active key has been verified at least once, you can drop the parameter.

Rollback plan#

Keep your old verification system running in parallel during migration:

async function verifyKey(apiKey) {  // Try Unkey first  const unkeyResult = await verifyWithUnkey(apiKey);  if (unkeyResult.valid) {    return unkeyResult;  }  // Fall back to legacy system (temporary)  const legacyResult = await verifyWithLegacy(apiKey);  if (legacyResult.valid) {    const maskedKey = apiKey.slice(0, 5) + "..." + apiKey.slice(-5);    console.log("Key found in legacy, not yet migrated:", maskedKey);  }  return legacyResult;}

Remove the fallback once migration is complete and verified.

Need help?#

Contact support

We'll help you plan and execute your migration safely.