doc: custom hostname PATCH requires type+method when changing CA

[dmmulroy]

Summary

• Documents that ssl.type and ssl.method are required when using PATCH to change ssl.certificate_authority on an existing custom hostname — omitting them silently fails or returns error 1434
• Adds examples and valid values across three pages: common API calls, certificate issuance, and troubleshooting

Changes

common-api-calls.mdx

• Updated "Edit custom hostname" table row to link to new CA switching section
• Added ### Change certificate authority subsection with valid values, method info, and two collapsible curl examples (switch to Google, reset to default)

issue-certificates.mdx

• Added ## Change certificate authority section between existing "Certificate authorities" and "Certificate details" sections
• Includes PATCH examples and a note on valid type/method values

troubleshooting.mdx

• Added ## Certificate authority change not taking effect via API troubleshooting entry with example and valid CA values

Context

The PATCH /zones/{zone_id}/custom_hostnames/{id} endpoint requires ssl.type ("dv") and ssl.method ("http"/"txt") when changing ssl.certificate_authority, but this wasn't documented. The API reference marks type and method as optional, which is misleading for this use case. Customers (notably beehiiv) hit error 1434 (ErrValidationTypeMethodRequired) when sending only certificate_authority.

[mitch292]

I think if we can just document at a high level that there are essentially two flavors of custom hostname SSL objects. "Managed" and "Custom". Managed means Cloudflare handles the lifecycle of the certificate (order / validation / renewal). Custom means a customer comes with a private key and certificate already.

When it's a managed custom hostname, two fields are always required in the PATCH

• ValidationType (json "type")
• ValidationMethod (json "method")

When it's custom, the requirements on the ssl object differ in the PATCH

• CustomCert (json "custom_cert") is always required
• One of CustomKey (json "custom_key") or CustomCSRID (json "custom_csr_id") is required

[mitch292]

LGTM - Thank you!

[elithrar]

/bonk review and suggest any fixes for style or code issues

[ask-bonk]

Good PR — this fills a real documentation gap that was causing customer-facing errors. The two-flavor (managed vs. custom certificate) structure that @mitch292 suggested has been incorporated well. A few suggestions below, mostly around consistency and reducing duplication.

Summary

• The content is technically sound and well-organized.
• Heading hierarchy, component imports, link format, and style are all correct.
• Main feedback: curl URL quoting should be consistent with existing examples, and the duplicated examples in issue-certificates.mdx could be replaced with a cross-reference to reduce maintenance surface.

[ask-bonk]

Consider replacing this entire section (the two Details blocks and the valid-values line) with a shorter cross-reference to common-api-calls.mdx, which now contains the authoritative examples. For example:

## Change certificate authority

To change the CA for an existing managed custom hostname, use the [Edit Custom Hostname](/api/resources/custom_hostnames/methods/edit/) PATCH endpoint. You must include `ssl.type` and `ssl.method` alongside `ssl.certificate_authority` — these fields are always required when editing a managed hostname's SSL settings.

This triggers certificate re-issuance with the new CA. For required fields, valid values, and curl examples, refer to [Edit custom hostname SSL](/cloudflare-for-platforms/cloudflare-for-saas/start/common-api-calls/#managed-certificates).

Duplicating the full curl examples across two pages creates a maintenance burden — if the API changes, both pages need updating.

[ask-bonk]

Review posted successfully. Here's a summary of what I flagged:

Overall: The PR is well-structured and addresses a real documentation gap. The managed vs. custom certificate split (per @mitch292's feedback) is cleanly implemented. MDX syntax, component imports, heading hierarchy, link format, and style are all correct.

Suggestions posted (6 inline comments):

1. Curl URL quoting (5 comments) — All new curl examples leave the URL unquoted, while the existing example in troubleshooting.mdx quotes it. URLs with {/} should be quoted for consistency and shell safety. Suggestions provided for all 5 instances across issue-certificates.mdx and common-api-calls.mdx.

2. Reduce duplication (1 comment) — The issue-certificates.mdx page duplicates the full curl examples already present in common-api-calls.mdx. Suggested replacing the duplicated Details blocks with a shorter paragraph that cross-references the authoritative examples in common-api-calls.mdx, reducing the maintenance surface.

github run