> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Migration

> Create a new migration / discovery job against an external secret store.

## 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`.

**`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)                            |

<CodeGroup>
  ```bash AWS Secrets Manager theme={"dark"}
  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"]
      }
    }'
  ```

  ```bash Azure Key Vault theme={"dark"}
  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"]
      }
    }'
  ```

  ```bash GCP Secret Manager theme={"dark"}
  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"]
      }
    }'
  ```
</CodeGroup>

### Response

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