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.

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,
  metadata
FROM api_keys
WHERE 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 support
const API_ID = "api_...";

// Your exported keys
const 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 verification
const isValid = await myDatabase.verifyKey(apiKey);

// After: Unkey verification
const 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.

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Migrate keys to Unkey

Prerequisites

Hash format

Export your keys

Example: PostgreSQL

Example: MongoDB

Hash your keys (if not already hashed)

Migrate to Unkey

Response

Key configuration options

Batch migrations

Update your verification

Rollback plan

Need help?

Contact support

​Prerequisites

​Hash format

​Export your keys

​Example: PostgreSQL

​Example: MongoDB

​Hash your keys (if not already hashed)

​Migrate to Unkey

​Response

​Key configuration options

​Batch migrations

​Update your verification

​Rollback plan

​Need help?

Contact support

Prerequisites

Hash format

Export your keys

Example: PostgreSQL

Example: MongoDB

Hash your keys (if not already hashed)

Migrate to Unkey

Response

Key configuration options

Batch migrations

Update your verification

Rollback plan

Need help?