DOC-2275: updates to cloud-troubleshooting.adoc with new links to `…

…invalid-api-key.adoc` page. (#3055)

* updates to  with new links to  page.

* make it clearer that there are two causes and solutions for the first issue

* undo previous commit 01fbca7

* DOC-2275: fixing up heading levels and document styling.

* Update changelog.md

---------

Co-authored-by: Farzad Hayatbakhsh <[email protected]>

changelog.md

@@ -7,6 +7,10 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 ### Unreleased
 
 
+### 2024-01-31
+
+- DOC-2275: updates to `cloud-troubleshooting.adoc` with new links to `invalid-api-key.adoc` page.
+
 ### 2024-01-30
 
 - DOC-2240: add new `understanding-editor-loads.adoc` to `how-to-guide` section.

modules/ROOT/pages/cloud-troubleshooting.adoc

@@ -7,26 +7,30 @@ When {cloudname} detects a problem, it will show an editor notification containi
 
 NOTE: The wording of the notifications shown here may differ from the actual notifications from {cloudname}.
 
-[[A-valid-API-key-is-required-starting-2024-to-continue-using-TinyMCE.-Please-alert-your-admin-to-sign-up-to-get-your-free-API-key.]]
-== "A valid API key is required, starting 2024, to continue using TinyMCE. Please alert your admin to sign-up to get your free API key."
+[[A-valid-API-key-is-required-to-continue-using-TinyMCE.-Please-alert-the-admin-to-check-the-current-API-key]]
+== "A valid API key is required to continue using {productname}. **Please alert the admin** to check the current API key. xref:invalid-api-key.adoc[Click here to learn more.]"
 
-=== Cause
+=== Scenario (one)
+
+==== Cause
 
 This notification is *only shown* when either:
 
 * An `+apiKey+` is not provided in the script tag.
 * `+no-api-key+` is provided as the API key.
 
-Such as:
+For example:
 
 [source,html,subs="attributes+"]
 ----
 <script src="{cdnurl}" referrerpolicy="origin"></script>
 ----
 
-=== Solution
+==== Solution
+
+Update the `+src+` URL to include your (website or application developer's) {cloudname} API Key. Your API key should replace the string `+no-api-key+`.
 
-Update the `+src+` URL to include your (website or application developer's) {cloudname} API Key. Your API key should replace the string `+no-api-key+`. For example, if your API is `+abcd1234+`:
+For example: if your API is `+abcd1234+`:
 
 [source,html,subs="attributes+"]
 ----
@@ -37,10 +41,9 @@ To retrieve your API key, or to sign up for an API key, visit: link:{accountsign
 
 NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}.
 
-[[A-valid-API-key-is-required-starting-2024-to-continue-using-TinyMCE.-Please-alert-your-admin-to-check-the-current-API-key]]
-== "A valid API key is required, starting 2024, to continue using TinyMCE. Please alert your admin to check the current API key."
+=== Scenario (two)
 
-=== Cause
+==== Cause
 
 This notification is shown when the API key provided cannot be found on the {cloudname} server.
 
@@ -50,7 +53,7 @@ The `+apiKey+` must be:
 * comprised of certain characters, and
 * created with a {cloudname} account on the link:{accountsignup}/[{accountpage} page].
 
-=== Solution
+==== Solution
 
 Check the `+apiKey+` provided in the script tag:
 
@@ -60,10 +63,14 @@ Check the `+apiKey+` provided in the script tag:
 
 NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}.
 
-[[This-domain-is-not-registered-with-Tiny-Cloud.-To-continue-using-TinyMCE-a-registered-domain-is-required-starting-2024.-Please-alert-your-admin-to-review-the-approved-domains-and-add-this-one-if-required.]]
-== "This domain is not registered with Tiny Cloud. To continue using TinyMCE, a registered domain is required, starting 2024. Please alert your admin to review the approved domains and add this one if required."
+'''
+
+[[This-domain-is-not-registered-in-the-TinyMCE-Customer-Portal.-Please-alert-the-admin-to-add-it-to-the-approved-domains-to-continue-using-TinyMCE.]]
+== "This domain is not registered in the {productname} Customer Portal. **Please alert the admin** to add it to the approved domains to continue using {productname}. xref:invalid-api-key.adoc[Click here to learn more.]"
+
+=== Scenario
 
-=== Cause
+==== Cause
 
 This notification is shown when the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer*] of the page does not match the list of approved domains stored against your `+apiKey+`. {cloudname} verifies the domain {productname} is loading from by checking the domain portion of the *Referer* header in the network request. You can view a list of your approved domains on your link:{accountpageurl}/[{accountpage}].
 
@@ -76,20 +83,24 @@ Sometimes the domain in the *Referer* header does not match with the URL in the
 
 In the section called *Request Headers* there should be a field for *Referer*. This is the value that {productname} is checking against your approved domains. It must match one of your approved domains listed on your link:{accountpageurl}/[{accountpage}].
 
-=== Solution
+==== Solution
 
 If the `+Referer+` is correct for the site, ensure that the domain is included in your list of approved domains on link:{accountpageurl}/[{accountpage}]. If the `+Referer+` is not what you are expecting, you may need to adjust your application's https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer* header] settings.
 
+'''
+
 [[were-unable-to-check-your-domain-because-the-referer-header-is-missing-please-read-the-guide-on-how-to-ensure-your-referer-header-is-present-so-we-can-then-customize-your-editor-experience]]
 == "We’re unable to check your domain because the referer header is missing. Please read the Guide on how to ensure your referer header is present, so we can then customize your editor experience."
 
-=== Cause
+=== Scenario
+
+==== Cause
 
 This notification is shown if the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer* header] is absent for the network request when loading {productname} from {cloudname}. {cloudname} verifies the domain {productname} is loading from by checking the domain of the *Referer* header in the network request.
 
 _Referer_ headers are sometimes removed by browser settings or browser extensions. {cloudname} only needs the domain in the *Referer* header, so for improved performance and privacy {companyname} recommends setting the `+referrerpolicy+` to `+origin+` when requesting {cloudname} resources.
 
-=== Solution
+==== Solution
 
 Identify which browser setting or extension is responsible for blocking the *Referer* being sent. A common extension is `+Referer Control+`:
 
@@ -98,16 +109,20 @@ Identify which browser setting or extension is responsible for blocking the *Ref
 
 Once you have identified the setting or extension, modify it to allow just the `+Origin+` of the `+Referer+` to be sent. Alternatively, disable the extension or setting for any pages using {cloudname}.
 
+'''
+
 [[the-___-premium-plugin-is-not-enabled-on-your-api-key-upgrade-your-account]]
 == "The ___ premium plugin is not enabled on your API key. Upgrade your account."
 
-=== Cause
+=== Scenario
+
+==== Cause
 
 This notification is shown when your API key does not have access to the premium plugin being requested. This could be the result of a trial expiring, and your {productname} configuration attempting to load premium plugins you can no longer access.
 
 You may also be seeing this notification if you are using the wrong API key. Ensure that you are using the API key that has the right entitlements.
 
-=== Solution
+==== Solution
 
 Either remove the premium plugin from your {productname} configuration, or upgrade your subscription to provide access to that premium plugin.