Skip to main content

​
POST /admin/migrations

Create a new migration / discovery job. KnoxCall runs a live probe against the provider before persisting — if the federation grant is broken, the request fails immediately with 400 and nothing is stored. Auth: requireOwnerOrAdmin — no step-up required.

​
Request body

FieldRequiredDescription
provider✅aws_sm | aws_ssm | azure_kv | gcp_sm
mode✅pull (server-side pull), capture (agent-side intercept), or both
credentials✅Provider-specific federation parameters (no static keys — see below)
scope—Provider-specific scope constraints (regions, vaults, etc.)
credentials by provider:
ProviderRequired fields
aws_sm / aws_ssmrole_arn (IAM role ARN), optionally external_id
azure_kvtenant_id (Azure AD GUID), client_id (app registration GUID) — uses WIF, no client_secret
gcp_smproject_number, workload_identity_pool, workload_identity_provider, service_account_email
Static credential fields (access_key_id, secret_access_key, client_secret, private_key, service_account_json, etc.) are rejected at the API level with 400. scope by provider:
ProviderOptional scope fields
aws_sm / aws_ssmregions (array of region strings), arn_allowlist
azure_kvsubscription_id (GUID), vault_names (array) — one of these is required
gcp_smproject_ids (array of GCP project ID strings)
curl -X POST https://admin.knoxcall.com/admin/migrations \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $KC_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws_sm",
    "mode": "pull",
    "credentials": {
      "role_arn": "arn:aws:iam::111122223333:role/KnoxCallMigrationReader",
      "external_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "scope": {
      "regions": ["us-east-1", "eu-west-1"]
    }
  }'

curl -X POST https://admin.knoxcall.com/admin/migrations \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $KC_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "azure_kv",
    "mode": "pull",
    "credentials": {
      "tenant_id": "aaaabbbb-cccc-dddd-eeee-ffffgggghhhh",
      "client_id": "11112222-3333-4444-5555-666677778888"
    },
    "scope": {
      "vault_names": ["my-prod-vault", "my-staging-vault"]
    }
  }'

curl -X POST https://admin.knoxcall.com/admin/migrations \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $KC_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gcp_sm",
    "mode": "pull",
    "credentials": {
      "project_number": "123456789012",
      "workload_identity_pool": "projects/123456789012/locations/global/workloadIdentityPools/knoxcall-pool",
      "workload_identity_provider": "projects/123456789012/locations/global/workloadIdentityPools/knoxcall-pool/providers/knoxcall-provider",
      "service_account_email": "migration-reader@my-project.iam.gserviceaccount.com"
    },
    "scope": {
      "project_ids": ["my-gcp-project"]
    }
  }'

​
Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "note": "Migration enqueued. Poll GET /admin/migrations/:id for discovery progress."
}