Docs: Document HTTP and GQL usage for EdgeDB Cloud users

docs/clients/graphql/index.rst

@@ -73,6 +73,12 @@ To execute a GraphQL query against the database ``edgedb`` on the instance
 named ``inst2``, we would send an HTTP request to
 ``http://localhost:10702/db/edgedb/graphql``.
 
+To determine the URL of an EdgeDB Cloud instance, find the host by running
+``edgedb instance credentials -I <org-name>/<instance-name>``. Use the
+``host`` and ``port`` from that table in the URL format at the top of this
+section. Change the protocol to ``https`` since EdgeDB Cloud instances are
+secured with TLS.
+
 .. note::
 
   The endpoint also provides a `GraphiQL`_ interface to explore the GraphQL

docs/clients/http/index.rst

@@ -4,6 +4,13 @@
 EdgeQL over HTTP
 ================
 
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    protocol
+    health-checks
+
 EdgeDB can expose an HTTP endpoint for EdgeQL queries. Since HTTP is a
 stateless protocol, no :ref:`DDL <ref_eql_ddl>`,
 :ref:`transaction commands <ref_eql_statements_start_tx>`,
@@ -37,10 +44,17 @@ Your instance can now receive EdgeQL queries over HTTP at
       called ``edgedb`` is created; all queries are executed against this
       database unless otherwise specified.
 
-    To determine the URL of a remote instance you have linked with the CLI, you
-    can get both the hostname and port of the instance from the "Port" column
-    of the ``edgedb instance list`` table (formatted as ``<hostname>:<port>``).
-    The same guidance on local database names applies here.
+    To determine the URL of an EdgeDB Cloud instance, find the host by running
+    ``edgedb instance credentials -I <org-name>/<instance-name>``. Use the
+    ``host`` and ``port`` from that table in the URL format above this note.
+    Change the protocol to ``https`` since EdgeDB Cloud instances are secured
+    with TLS.
+
+    To determine the URL of a self-hosted remote instance you have linked with
+    the CLI, you can get both the hostname and port of the instance from the
+    "Port" column of the ``edgedb instance list`` table (formatted as
+    ``<hostname>:<port>``). The same guidance on local database names applies
+    here.
 
 
 .. _ref_http_auth:
@@ -56,7 +70,7 @@ By default, the HTTP endpoint uses :eql:type:`cfg::Password` based
 authentication, in which
 `HTTP Basic Authentication
 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme>`_
-is used to provide an edgedb username and password.
+is used to provide an EdgeDB username and password.
 
 .. lint-on
 
@@ -82,10 +96,17 @@ behavior::
     ... };
     OK: CONFIGURE INSTANCE
 
+To authenticate to your EdgeDB Cloud instance, first create a secret key using
+the EdgeDB Cloud UI or :ref:`ref_cli_edgedb_cloud_secretkey_create`. Use the
+secret key as your token with the bearer authentication method. Here is an
+example showing how you might send the query ``select Person {*};`` using cURL:
 
-.. toctree::
-    :maxdepth: 2
-    :hidden:
+.. lint-off
 
-    protocol
-    health-checks
+.. code-block:: bash
+
+    $ curl -G https://<cloud-instance-host>:<cloud-instance-port>/db/edgedb/edgeql \
+       -H "Authorization: Bearer <secret-key> \
+       --data-urlencode "query=select Person {*};"
+
+.. lint-on