Migration API
Legacy Migrator data API — handshake, sessions, preflight, batch upload, finalize, and verify.
Where do I get a key?
Migration API keys are created from your tenant workspace under Settings → Migration API Keys. The full key (prefix egk_mig_) is shown once at creation — store it securely. If it is lost, rotate the key to issue a new one.
Authentication
| Header / Setting | Value |
|---|---|
Base URL |
Shown once when the key is generated, e.g. https://<your-egkits-server>/api/v1/migration |
X-Api-Key |
The full migration key, including the prefix and the dot:
egk_mig_xxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
The masked fingerprint (ending with ****) cannot authenticate. |
Authorization |
Alternative to X-Api-Key: Authorization: MigrationKey <full api key> |
Migration flow
handshake → sessions → preflight → batches ×N → finalize → verifyKeys are bound to a tenant and an environment scope (testing, production, or both) — a mismatch between the key's scope and the session's targetEnvironment returns 401.
Keys may restrict modules: itemCodes, sentInvoices, receivedInvoices, receipts. Upload modules in that dependency order.
Network restrictions (CIDR allow-list) and expiry apply per key. Rate limit is 120 requests/minute per key.
Enum values serialize as camelCase strings; timestamps are ISO-8601.
Quick test (cURL / Postman)
curl -X POST "https://<your-server>/api/v1/migration/handshake" \
-H "X-Api-Key: egk_mig_4f2a91c07d3e.q8PzR5tWvYxA1bC3dE6fG9hJ2kM4nP7sT0uVwXyZabc" \
-H "Content-Type: application/json" \
-d "{ \"clientVersion\": \"1.4.0\", \"clientProtocolVersion\": \"1.0\", \"targetEnvironment\": \"testing\" }"Error envelope
Failures return a structured error. Codes: MIG_AUTH_001 (401 auth), MIG_VAL_001 (400 validation), MIG_SESSION_404 (unknown session). Null fields are omitted.
{
"errorCode": "MIG_AUTH_001",
"category": "authentication",
"reason": "Invalid, revoked, expired, or environment-mismatched migration API key.",
"suggestedResolution": "Verify the X-Api-Key header and that the key is active for this environment."
}