GitBook custom domain HTTPS certificate validation scope

GitBook custom domain certificates cover the exact hostname only

GitBook provisions a managed TLS certificate for the specific hostname entered in a space's domain settings once DNS validation succeeds. It does not automatically issue a wildcard certificate for *.example.com when you configure a single subdomain such as docs.example.com. Each nested hostname—for example api.docs.example.com—must be added as its own custom domain and validated separately.

Confirmed vs. likely behavior

The documented custom domain flow ties certificate issuance to the exact hostname configured in the dashboard. There is no documented statement that a wildcard certificate is provided automatically, and the standard flow does not describe wildcard DNS triggering wildcard TLS coverage. Treat any assumption of automatic *.example.com coverage as unconfirmed until GitBook's current documentation or support explicitly states otherwise.

Steps for nested hostnames

1. Open the target space's domain settings and add the exact nested hostname (e.g., api.docs.example.com).
2. Create the DNS record shown in the dashboard—typically a CNAME for subdomains. Apex domains use different record types.
3. Wait for GitBook to validate the record and issue the certificate. Renewal timing and detailed renewal diagnostics are limited in the dashboard.
4. Verify the served certificate scope externally.

Verifying certificate scope

Use a scoped TLS inspection to confirm the certificate matches the exact hostname and contains no wildcard SAN:

openssl s_client -connect api.docs.example.com:443 -servername api.docs.example.com | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

Look for the exact DNS entry in the SAN list. If only the parent hostname appears, the nested subdomain is not covered.

Plan and apex considerations

Apex domains and certain plan-dependent features follow different DNS requirements than subdomain CNAMEs. Always copy the target value directly from your space's domain settings rather than relying on remembered hostnames, because GitBook's target may change over time.

One detail would change where you configure this: is the nested hostname meant to serve the same GitBook space as the parent domain, or a different space? If it is a different space, the custom domain entry must be created in that space's settings; sharing a single certificate across multiple spaces is not documented.