Update a Credential

Description

Updates an active Credential in place under the specified Vault. The request uses merge-style patch semantics: omitted fields keep their current values, which supports secret rotation without recreating the Credential. Forward verifies that the caller has write access to the parent Vault. Sensitive authentication fields are write-only and are never echoed in the response.

Path

POST /api/v1/forward/vaults/{id}/credentials/{cred_id}

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Vault ID.
`cred_id`	string	Yes	Credential ID.

Query parameters

Parameter	Type	Required	Description
`identity_id`	string	No	Optional; used only for Identity-owned resources. PAT callers can pass it explicitly; omitting it uses the administrator scope. For SAT, issue an Identity-scoped token and do not explicitly pass this parameter, or the request returns HTTP 400. See Identity ownership.

Request body

The request uses partial-update semantics. Only auth and metadata are accepted, and at least one field is required.

Field	Type	Required	Description
`auth`	object	No	Partially updates authentication information for the current Credential type. It must include a `type` that matches the current type.
`metadata`	object \| null	No	Applies a merge patch to the existing metadata. A `null` value in the object removes that key; top-level `null` clears all metadata. `created_by` is reserved and cannot be updated.

The Credential type, MCP Server URL, environment-variable secret_name, and the client_id and token_endpoint in an OAuth refresh configuration cannot be changed through this endpoint.

`static_bearer`

Field	Type	Required	Description
`type`	string	Yes	Must be `static_bearer`.
`token`	string	No	Replaces the Bearer token. Write-only and never returned in responses.

`mcp_oauth`

Field	Type	Required	Description
`type`	string	Yes	Must be `mcp_oauth`.
`access_token`	string	No	Replaces the access token.
`expires_at`	string \| null	No	RFC 3339 time. Use `null` to clear the expiration time.
`refresh`	object	No	Partially updates the existing refresh configuration. It cannot add a refresh configuration to a Credential that does not already have one.

The refresh object supports:

Field	Type	Required	Description
`refresh_token`	string	No	Replaces the refresh token.
`scope`	string \| null	No	Replaces or clears the scope.
`token_endpoint_auth`	object	No	Updates the token endpoint authentication configuration.

`environment_variable`

Field	Type	Required	Description
`type`	string	Yes	Must be `environment_variable`.
`secret_value`	string	No	Replaces the secret value. Write-only and never returned in responses.

Example request

curl -X POST "https://api.qoder.com/api/v1/forward/vaults/vault_xxx/credentials/vcred_xxx" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "static_bearer",
      "token": "new-secret-token"
    },
    "metadata": {
      "rotated_by": "console"
    }
  }'

Example response

HTTP 200 OK

{
  "id": "vcred_xxx",
  "type": "vault_credential",
  "vault_id": "vault_xxx",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://mcp.example.com"
  },
  "display_name": "",
  "metadata": {
    "rotated_by": "console"
  },
  "archived_at": null,
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-08-27T12:00:00Z"
}

The response is a Vault credential object. Token, secret, and other sensitive fields are never returned.

Credential updates are write-only. If the client does not receive a successful response, a subsequent GET can read only the redacted state and cannot prove whether the new secret took effect. Do not automatically retry a secret update.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	The request body or path parameters are invalid. This includes no updatable fields, unsupported fields, a missing or mismatched `auth.type`, invalid field values, or an attempt to update `refresh` when no refresh configuration exists.
400	`invalid_request_error`	If the reserved key `created_by` is supplied, `message` is `metadata key "created_by" is reserved`.
401	`authentication_error`	The authentication token is missing or invalid.
403	`permission_error`	The caller cannot access the parent Vault or Credential.
404	`not_found_error`	The Vault or Credential does not exist or is not visible.
409	`conflict_error`	The Vault or Credential is archived, or the resource state conflicts.
500/502/503	`api_error`	Forward or a dependent service failed.

Authentication information in Credential requests is sensitive. Some detailed validation messages are replaced by a generic redacted message; the HTTP status and error type remain unchanged.

​Description

​Path

​Request headers

​Path parameters

​Query parameters

​Request body

​static_bearer

​mcp_oauth

​environment_variable

​Example request

​Example response

​Errors