Skip to main content

​
Prerequisites

  • Create an Unkey account.
  • Create a Workspace and API. Save the workspaceId and apiId for later use.
    • The workspaceId can be found in the upper right corner after navigating to Settings/General in the side menu.
      Workspace Page
    • The apiId can be found in the upper right corner after navigating to APIs/<Your API> in the side menu.
      Api Page
  • Create a Root Key under the Settings menu. It will need the api.*.create_key permission or api.<api_id>.create_key to migrate to a specific API.
  • Email us to get a migrationId at [email protected] with:
    • Your workspace ID.
    • What service the keys will be migrated from.
Extracting keys from your current system is likely the hardest part. It depends on how your keys are stored and how you can access them. Some providers have APIs to list all keys, while others require you to manually export them. You will need to provide the hash of your keys, as well as other settings to Unkey via the keys.migrateKeys endpoint.

​
Node.js Example

const { createHash } = require("node:crypto")

function hash(key) {
  return {
    value: createHash("sha256").update(key).digest("base64"),
    variant: "sha256_base64",
  }
}

const request = {
  migrationId: "<UNKEY_MIGRATION_ID>", // the id of the migration you created
  apiId: "<UNKEY_API_ID>", // the id of the API you created
  keys: [
    {
      hash: hash("my-secret-key"),
      //... other settings
    },
    {
      hash: hash("my-other-secret-key"),
      //... other settings
    },
  ]
}

fetch("https://api.unkey.com/v2/keys.migrateKeys", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <UNKEY_ROOT_KEY>",
  },
  body: JSON.stringify(request)
})
.then(res => res.json())
.then(res => {
  console.log("Migrated keys:", res.data.migrated)
  console.log("Failed hashes:", res.data.failed)
})

​
Response

The endpoint returns a list of successfully migrated keys and any failed hashes: 
{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "migrated": [
      {
        "hash": "abc123...",
        "keyId": "key_123"
      }
    ],
    "failed": []
  }
}
Failed hashes indicate hashes that could not be migrated (e.g., already exist in the system).