Rotate a credential's secret or update metadata. The name and networking settings cannot be changed.
Endpoint
POST /vaults/{vault_id}/credentials/{credential_id}
Paths are relative to the Base URL. Send Authorization: Bearer $DASHSCOPE_API_KEY on every request. For authentication details, see Authentication.
Path parametersvault_idstring (required)Parent vault ID. Treat it as an opaque IDcredential_id string (required)Credential ID. Treat it as an opaque IDRequest bodymetadataobject (optional)Metadata, when omitted, the current value is kept; null returns 400; {} clears it. Up to 16 items; key 1–64 characters, value up to 512 charactersauth object (optional)Authentication information, when omitted, only metadata is updated; null returns 400
Properties type string (conditional)Authentication type, fixed as environment_variablesecret_value string (conditional)New secret value. Cannot be empty or whitespace-only; length and control character limits are the same as on createmetadata and auth. Omitting both or sending {} returns 400. Updates can only change metadata and rotate secret_value; name, secret_name, and networking cannot be changed, and sending these fields returns 400 unknown_parameter.metadata is replaced as a whole, not merged. Rotation keeps the existing environment variable name and networking settings. The response does not return secret_value, the key identifier, or injection_location. | Request example |
Response fields200, returns the updated credential:id stringCredential IDobject stringCredential object type, fixed as vault.credentialvault_id stringParent vault IDname stringDisplay namecreated_at integerCreation time in Unix secondsupdated_at integerLast update time in Unix secondsmetadata objectMetadata, string key-value pairs; {} when not setauth objectAuthentication settings.
Properties type stringAuthentication type, fixed as environment_variablesecret_name stringEnvironment variable namenetworking objectTarget domain settings.
Properties type stringNetwork access type, limited or unrestrictedallowed_hosts arrayDomains or IPv4 addresses allowed for limited | Response example |
Error codes
For the error response structure, see Errors.
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / unknown_parameter | The request contains an unknown field, such as name, secret_name, or networking |
400 | invalid_request_error / invalid_type | Fix the field type as described |
400 | invalid_request_error / invalid_request_error | The request body is empty, auth.type is invalid, secret_value is blank, or metadata is null |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | The credential does not exist, is deleted, does not belong to the parent vault, or belongs to another workspace |
409 | conflict_error / conflict_error | Retry later. If it keeps failing, submit a ticket with x-request-id |
500 | server_error / server_error | Retry later. If it keeps failing, submit a ticket with x-request-id |