---
title: "Set or rotate a connection's encrypted credential."
method: PUT
path: "/v1/connections/{id}/credentials"
tags: ["connections"]
---

# Set or rotate a connection's encrypted credential.

`PUT /v1/connections/{id}/credentials`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/connections/{id}/credentials`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Stores the credential for a `service_secret` / `service_keypair` connection.
The plaintext is sent over HTTPS, forwarded to the engine credential broker to
be envelope-encrypted (ADR-0012), and never stored in cleartext or echoed back.
Idempotent — a re-PUT rotates the stored secret. Rejected (400) for
`oauth_passthrough` (secrets are per-user grants collected via the OAuth consent
flow) and `cloud_iam` (workload-derived). Admin or above. Returns no body.

## Request body

- object
  - `secret` string, required: The plaintext credential — a password, token, or private-key PEM. Never returned.

## Response `204`

Credential stored (no body — the secret is never echoed).

## Other responses

- `400`: Empty secret, or the connection's auth method stores no inline credential.
- `401`: Missing, invalid, or expired session.
- `403`: The caller's role does not permit this action.
- `404`: Resource does not exist.
- `502`: The credential broker (engine) could not be reached.
- `503`: Credential encryption is not configured on this deployment (CONNECTION_KEK unset).

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)