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

# Secret Store Migrations overview

> Migrate secrets from AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager into KnoxCall with zero downtime and zero plaintext exposure.

# Secret Store Migrations overview

If your secrets currently live in AWS Secrets Manager, AWS SSM Parameter Store, Azure Key Vault, or GCP Secret Manager, the Secret Store Migration feature lets you move them into KnoxCall — without changing application code and without any secrets ever touching disk during the migration.

The goal: KnoxCall becomes the single place your team manages, audits, and rotates credentials, regardless of which cloud provider currently holds them.

## How it works

The KnoxCall agent runs alongside your applications. During a migration, the agent acts as an intermediary:

* **Bucket A (HTTPS APIs)**: the agent intercepts API calls your application makes to the cloud secret store, rewrites the authentication, and forwards the secret from KnoxCall instead. No code change in your app.
* **Bucket B (Databases)**: the agent binds a local TCP port on `127.0.0.1`. Your application connects to `127.0.0.1:{port}` instead of the database host directly. The agent handles all authentication to the real database and pipes the connection through.

|                           | Bucket A — HTTPS APIs                     | Bucket B — Databases                           |
| ------------------------- | ----------------------------------------- | ---------------------------------------------- |
| **Mechanism**             | Agent TLS intercept + auth header rewrite | Agent TCP proxy (localhost listener)           |
| **Code changes required** | None                                      | Change connection string to `127.0.0.1:{port}` |
| **Source stores**         | AWS SM, AWS SSM, Azure KV, GCP SM         | Any database with credentials in those stores  |
| **Protocols**             | HTTPS                                     | PostgreSQL, MySQL, MongoDB, Redis              |
| **Plaintext exposure**    | Never                                     | Never                                          |

## Migration phases

Every migration moves through this lifecycle:

```text theme={"dark"}
pending → discovering → awaiting_review → completed
```

| Status            | What's happening                                                               |
| ----------------- | ------------------------------------------------------------------------------ |
| `pending`         | Migration created; discovery job not yet started                               |
| `discovering`     | Agent or pull worker scanning the secret store for credentials                 |
| `awaiting_review` | Discovery complete; items are queued for reviewer decisions (approve / reject) |
| `completed`       | All approved items written to KnoxCall secrets; migration closed               |
| `cancelled`       | Migration cancelled by operator                                                |

You can cancel a migration in the `pending`, `discovering`, or `awaiting_review` phase. Once `completed`, the migration is terminal.

## Source stores supported

| Provider                | API secrets | DB credentials |
| ----------------------- | ----------- | -------------- |
| AWS Secrets Manager     | ✅ Bucket A  | ✅ Bucket B     |
| AWS SSM Parameter Store | ✅ Bucket A  | —              |
| Azure Key Vault         | ✅ Bucket A  | ✅ Bucket B     |
| GCP Secret Manager      | ✅ Bucket A  | ✅ Bucket B     |

## Quick start

### Via admin UI

1. Go to **Infrastructure → Secret Store Migrations**
2. Click **New Migration**
3. Choose your source provider and bucket type
4. Follow the setup wizard

### Via API

```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/admin/migrations \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws_sm",
    "mode": "pull",
    "credentials": {
      "role_arn": "arn:aws:iam::111122223333:role/KnoxCallMigrationReader",
      "external_id": "your-chosen-external-id"
    },
    "scope": {
      "regions": ["us-east-1"]
    }
  }'
```

Provider values: `aws_sm`, `aws_ssm`, `azure_kv`, `gcp_sm`. Mode values: `pull`, `capture`, `both`. Static credentials (`access_key_id`, `client_secret`, etc.) are rejected — use IAM role assumption or WIF. See the [Migrations API reference](/api-reference/migrations) for full field documentation per provider.

<CardGroup cols={2}>
  <Card title="Bucket A: HTTPS API migration" icon="shield" href="/essentials/migrations/bucket-a-https">
    Zero-plaintext cutover for HTTP/HTTPS secret store consumers
  </Card>

  <Card title="Bucket B: Database migration" icon="database" href="/essentials/migrations/bucket-b-databases">
    Localhost TCP proxy for database credential migration
  </Card>

  <Card title="Agent database proxy protocols" icon="server" href="/essentials/migrations/agent-db-proxy">
    Technical reference for PostgreSQL, MySQL, MongoDB, Redis wire protocols
  </Card>

  <Card title="Migration verification" icon="check-circle" href="/essentials/migrations/verification">
    DNS/TLS probes, operator confirmation, and safe-to-delete status
  </Card>

  <Card title="Migrations API reference" icon="square-terminal" href="/api-reference/migrations">
    Full endpoint reference
  </Card>

  <Card title="KnoxCall agent" icon="box" href="/infrastructure/go-agent">
    Install and configure the self-hosted proxy agent
  </Card>
</CardGroup>