Create Migration

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

Field	Required	Description
`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:

Provider	Required fields
`aws_sm` / `aws_ssm`	`role_arn` (IAM role ARN), optionally `external_id`
`azure_kv`	`tenant_id` (Azure AD GUID), `client_id` (app registration GUID) — uses WIF, no client_secret
`gcp_sm`	`project_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.

Federation subject

KnoxCall signs a short-lived OIDC assertion that your cloud provider validates against its trust policy. The sub claim is specific to your tenant:

knoxcall-migration:<your-KnoxCall-tenant-id>

Configure that exact value — Azure’s federated-credential Subject, or a GCP WIF attribute condition such as attribute.sub == "knoxcall-migration:<your-KnoxCall-tenant-id>". The New Migration page shows the correct string for the tenant you are signed into.

Earlier connections were told to trust the bare constant knoxcall-migration, which was identical for every KnoxCall customer — any KnoxCall tenant’s assertion satisfied a trust policy naming it. Existing migrations keep working on the old subject, but update your trust policy to the tenant-specific value. The assertion also carries a knoxcall_tenant_id claim you can gate on immediately if you would rather add an attribute condition than re-cut the subject.

scope by provider:

Provider	Optional scope fields
`aws_sm` / `aws_ssm`	`regions` (array of region strings), `arn_allowlist`
`azure_kv`	`subscription_id` (GUID), `vault_names` (array) — one of these is required
`gcp_sm`	`project_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."
}

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

POST /admin/migrations

Request body

Federation subject

Response

​POST /admin/migrations

​Request body

​Federation subject

​Response

POST /admin/migrations

Request body

Federation subject

Response