Sign in

v66

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
keys

Migrate API key(s)

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)
post/v2/keys.migrateKeys

Request body

migrationIdstring required

Identifier of the configured migration provider/strategy to use (e.g., "your_company"). You will receive this from Unkey's support staff.

apiIdstring required

The ID of the API that the keys should be inserted into

Example request

{
  "migrationId": "your_company",
  "apiId": "api_123456789",
  "keys": [
    {
      "hash": "your_already_hashed_key",
      "name": "Payment Service Production Key",
      "externalId": "user_1234abcd",
      "meta": {
        "plan": "enterprise",
        "featureFlags": {
          "betaAccess": true,
          "concurrentConnections": 10
        },
        "customerName": "Acme Corp",
        "billing": {
          "tier": "premium",
          "renewal": "2024-12-31"
        }
      },
      "roles": [
        "api_admin",
        "billing_reader"
      ],
      "permissions": [
        "documents.read",
        "documents.write",
        "settings.view"
      ],
      "enabled": true,
      "credits": {
        "remaining": 1000,
        "refill": {
          "interval": "daily",
          "amount": 1000,
          "refillDay": 15
        }
      },
      "ratelimits": [
        {
          "name": "requests",
          "limit": 100,
          "duration": 60000,
          "autoApply": true
        },
        {
          "name": "heavy_operations",
          "limit": 10,
          "duration": 3600000,
          "autoApply": false
        }
      ]
    }
  ]
}

Response

Successfully migrated keys.

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "migrated": [
      {
        "hash": "sha256_abc123def456",
        "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q"
      }
    ],
    "failed": [
      "sha256_ghi789jkl012"
    ]
  }
}