Update Credential

Update an existing credential. A `value` already confirmed on another account is stored like any other, unvalidated, and answered like any other — no code that could confirm it is sent, and the account that holds it is notified that an attempt was made. A `value` the caller already holds on another credential of their own answers `409 users_m.duplicate_credential`. Uniqueness counts confirmed credentials only; surrounding whitespace is trimmed before the value is compared and stored, and the comparison is case-insensitive for every credential type. A `value` that is empty after trimming is treated as absent: the credential is left untouched and no code is issued. Re-submitting the value the credential already holds is not a change and is not checked, but it still un-validates the credential and re-issues a code. Changing `value` re-issues a one-time code, so the OTP refusals reach this path: `429 otp_m.cooling_period_active`, `500 otp_m.failed_send_otp`, `500 otp_m.cache_error`. Send pacing answers success with `code_sent: false` and a `retry_after`; only where no code is left does it answer `429 otp_m.resend_too_soon` or `429 otp_m.resend_limit_exceeded`. A `value` that cannot be delivered to is refused with `400` before the row is written: `users_m.invalid_phone` for a phone number that does not parse — one without a country code, for instance — and `users_m.invalid_email`, `users_m.invalid_email_spaces` or `users_m.invalid_email_length` for an e-mail. Credential types this module does not shape-check are unaffected.

curl -X PUT "https://example.com/v1/users/credentials/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "type": "email",
  "value": "string",
  "validated": true,
  "preferred": true,
  "active": true,
  "metadata": {},
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "modified_at": "2019-08-24T14:15:22Z",
  "modified_by": "e8d4374d-93a1-4e98-a6c6-fdcf00c5059f",
  "code_sent": true,
  "message": "string",
  "retry_after": 30
}

{
  "status": 400,
  "message": "Invalid user input",
  "code": "users_m.invalid_user_input",
  "class": "validation"
}

{
  "status": 401,
  "message": "Unauthorized",
  "code": "common.unauthorized",
  "class": "business"
}

{
  "status": 403,
  "message": "No access to the record",
  "code": "common.rbac_no_rec_access",
  "class": "business"
}

{
  "status": 404,
  "message": "User not found",
  "code": "common.user_not_found",
  "class": "business"
}

{
  "status": 409,
  "message": "Credential already exists",
  "code": "users_m.duplicate_credential",
  "class": "business"
}

{
  "status": 429,
  "code": "otp_m.cooling_period_active",
  "message": "In cooling period for 1 minute, 60 second(s) left",
  "class": "temporary",
  "retryable": true
}

{
  "status": 500,
  "message": "Failed to extract claims",
  "code": "auth.failed_to_extract_claims",
  "class": "business"
}

{
  "overall_status": "unhealthy",
  "message": "Service is shutting down",
  "timestamp": "2026-08-27T15:04:05Z"
}