# Manage a source

Test a source's credential, sync it, rename it, replace its token, change its settings, or disconnect it.

Replace _4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a_ with the source's id.

## Prerequisites

- To test, `secrets:UseSecretSource` on the source; to sync, `secrets:SyncSecret`; to rename,
  replace the token or change settings, `secrets:UpdateSecretSource`; to disconnect,
  `secrets:DeleteSecretSource`.
- In the console, also `secrets:ListSecretSources` to open **Sources**; without it the page says
  your policies do not grant it.

## Test, sync, rename, replace the token

**Console**
1. Open **Sources** (in the Secrets navigation).
2. On the source's row, choose **Sync now**, or open the **⋯** menu and choose **Test connection**,
   **Rename** or **Replace token**.
3. For **Rename**, enter the new name and choose **Rename**. For **Replace token**, paste the new
   token and choose **Verify & replace**.

The row shows the status, the refresh interval, the last sync and how many synced secrets fail.

**CLI**
```sh
dcloud secrets sources test 4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
dcloud secrets sources sync 4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
dcloud secrets sources update 4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a --name dialog-staging
```

**API**
```http
PATCH /secrets/api/sources/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
{ "name": "dialog-staging", "refreshIntervalMinutes": 120 }
```

`POST …/sources/{id}/test` and `POST …/sources/{id}/sync` take no body.

**Terraform**
Change `name`, `credential`, `config` or `refresh_interval_minutes` on the `dcloud_secrets_source`.

- **Test** answers `200` with `ok: true` and what the credential reaches, or `ok: false` and the
  error; the source's status is set to match.
- **Sync** refreshes every secret synced from the source and answers how many were checked,
  changed and failed.
- **Rename** renames the credential secret to match (`SOURCE_<NAME>_TOKEN`). Synced secrets follow
  the source by id, so nothing else changes; scripts that pass the old name as `source` need the
  new one.
- **A new token or new settings** are verified with the provider first; a refusal leaves the token,
  the settings, the description and the refresh interval as they were. A new `name` in the same
  request is applied before that check, so it stays even when the request is refused: rename in a
  request of its own. A new token is written as a new version of the credential secret. `config`
  replaces the settings whole.

## Disconnect

**Console**
1. On the source's row, open the **⋯** menu and choose **Disconnect**.
2. Choose **Disconnect**.

**CLI**
```sh
dcloud secrets sources delete 4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
```

**API**
```http
DELETE /secrets/api/sources/4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
```

**Terraform**
Remove the `dcloud_secrets_source` and run `terraform apply`.

Disconnecting deletes the credential secret with the source. It is refused while anything still
syncs from it.

## Refusals

- `409` "2 secret(s) still sync from "prod-1password" (OPENAI_API_KEY, DB_PASSWORD). Delete them,
  or keep the source."
- `409` "1 SSH key pair(s) still sync their public key from "prod-1password". Delete them under KMS
  → SSH key pairs, or keep the source."
- `409` "A source named dialog-staging exists", or "A secret named SOURCE_DIALOG_STAGING_TOKEN
  already exists".
- `400` for invalid settings, such as "The address must be https://".
- `422` "1Password rejected the credential: …" or "… did not accept the new settings: …".

## Related

- [Sync a secret from a source](sync-a-secret-from-a-source.md)
- `secrets.sources.update` · `secrets.sources.delete` · `dcloud_secrets_source`
