API Docs: create `Authentication` page and order sidebar menu (#92900)

* API Docs: create `Authentication` page and order sidebar menu

* fix minor typos

* Update capitalization

We don't capitalize titles as per https://grafana.com/docs/writers-toolkit/write/style-guide/capitalization-punctuation/

* Update docs/sources/developers/http_api/examples/_index.md

Co-authored-by: Jack Baldry <jack.baldry@grafana.com>

* Update docs/sources/developers/http_api/authentication.md

Co-authored-by: Jack Baldry <jack.baldry@grafana.com>

---------

Co-authored-by: Irene Rodriguez <irene.rodriguez@grafana.com>
Co-authored-by: Jack Baldry <jack.baldry@grafana.com>

docs/sources/developers/http_api/_index.md

@@ -27,40 +27,11 @@ Since version 8.4, HTTP API details are [specified](https://editor.swagger.io/?u
 
 Starting from version 9.1, there is also a [OpenAPI v3 specification](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/openapi3.json) (generated by the v2 one).
 
-Users can browser and try out both via the Swagger UI editor (served by the grafana server) by navigating to `/swagger-ui`.
+Users can browser and try out both via the Swagger UI editor (served by the Grafana server) by navigating to `/swagger-ui`.
 
-## Authenticating API requests
+## Authenticate API requests
 
-You can authenticate requests using basic auth, a service account token or a session cookie (acquired using regular login or OAuth).
+{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}
-
-### Basic Auth
-
-If basic auth is enabled (it is enabled by default), then you can authenticate your HTTP request via
-standard basic auth. Basic auth will also authenticate LDAP users.
-
-curl example:
-
-```bash
-curl http://admin:admin@localhost:3000/api/org
-{"id":1,"name":"Main Org."}
-```
-
-### Service Account Token
-
-To create a service account token, click on **Administration** in the left-side menu, click **Users and access**, then **Service Accounts**.
-For more information on how to use service account tokens, refer to the [Service Accounts]({{< relref "../../administration/service-accounts/" >}}) documentation.
-
-You use the token in all requests in the `Authorization` header, like this:
-
-**Example**:
-
-```http
-GET http://your.grafana.com/api/dashboards/db/mydash HTTP/1.1
-Accept: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
-```
-
-The `Authorization` header value should be `Bearer <your service account token>`.
 
 ## X-Grafana-Org-Id Header
 
@@ -110,7 +81,7 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 
 ## Grafana Enterprise HTTP APIs
 
-Grafana Enterprise includes all of the Grafana OSS APIs as well as those that follow:
+Grafana Enterprise includes all of the Grafana OSS APIs as well as the following APIs:
 
 - [Data source permissions API]({{< relref "datasource_permissions/" >}})
 - [License API]({{< relref "licensing/" >}})

docs/sources/developers/http_api/authentication.md

@@ -0,0 +1,23 @@
+---
+canonical: https://grafana.com/docs/grafana/latest/developers/http_api/authentication/
+description: 'You can authenticate HTTP API requests using basic authentication, a service account token, or a session cookie.'
+keywords:
+  - grafana
+  - http
+  - documentation
+  - api
+  - role-based-access-control
+  - acl
+  - enterprise
+labels:
+  products:
+    - enterprise
+    - oss
+title: Authentication options for the HTTP API
+menuTitle: Authentication
+weight: 01
+---
+
+# Authentication options for the HTTP API
+
+{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}

docs/sources/developers/http_api/examples/_index.md

@@ -0,0 +1,18 @@
+---
+canonical: https://grafana.com/docs/grafana/latest/developers/http_api/examples/
+keywords:
+  - grafana
+  - tutorials
+  - API
+labels:
+  products:
+    - enterprise
+    - oss
+title: 'HTTP API examples'
+menuTitle: 'Examples'
+weight: 02
+---
+
+# HTTP API examples
+
+{{< section >}}

docs/sources/developers/http_api/examples/create-api-tokens-for-org.md

@@ -1,8 +1,8 @@
 ---
 aliases:
-  - ../../http_api/create-api-tokens-for-org/
+  - ../../../http_api/create-api-tokens-for-org/ # /docs/grafana/<GRAFANA_VERSION>/http_api/create-api-tokens-for-org/
-  - ../../tutorials/api_org_token_howto/
+  - ../../../tutorials/api_org_token_howto/ # /docs/grafana/<GRAFANA_VERSION>/tutorials/api_org_token_howto/
-canonical: /docs/grafana/latest/developers/http_api/create-api-tokens-for-org/
+canonical: /docs/grafana/latest/developers/http_api/examples/create-api-tokens-for-org/
 keywords:
   - grafana
   - tutorials
@@ -15,7 +15,6 @@ labels:
     - enterprise
     - oss
 title: 'API Tutorial: Create Service Account tokens and dashboards for an organization'
-weight: 150
 ---
 
 # Create Service Account tokens and dashboards for an organization

docs/sources/developers/http_api/examples/curl-examples.md

@@ -1,7 +1,8 @@
 ---
 aliases:
-  - ../../http_api/curl-examples/
+  - ../../../http_api/curl-examples/ # /docs/grafana/<GRAFANA_VERSION>/http_api/curl-examples/
-canonical: /docs/grafana/latest/developers/http_api/curl-examples/
+  - ../../http_api/curl-examples/ # /docs/grafana/<GRAFANA_VERSION>/developers/http_api/curl-examples/
+canonical: /docs/grafana/latest/developers/http_api/examples/curl-examples/
 description: cURL examples
 keywords:
   - grafana

docs/sources/shared/developers/authentication.md

@@ -0,0 +1,36 @@
+---
+headless: true
+comments: |
+  This file is used in the following files: developers/http_api/{_index.md,authentication.md}
+---
+
+You can authenticate HTTP API requests using basic authentication, a service account token, or a session cookie (acquired via regular login or OAuth).
+
+### Basic auth
+
+If basic auth is enabled (it is enabled by default), then you can authenticate your HTTP request via
+standard basic auth. Basic auth will also authenticate LDAP users.
+
+curl example:
+
+```bash
+curl http://admin:admin@localhost:3000/api/org
+{"id":1,"name":"Main Org."}
+```
+
+### Service account token
+
+To create a service account token, click on **Administration** in the left-side menu, click **Users and access**, then **Service Accounts**.
+For more information on how to use service account tokens, refer to the [Service Accounts]({{< relref "../../administration/service-accounts/" >}}) documentation.
+
+You use the token in all requests in the `Authorization` header, like this:
+
+**Example**:
+
+```http
+GET http://your.grafana.com/api/dashboards/db/mydash HTTP/1.1
+Accept: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+The `Authorization` header value should be _`Bearer <YOUR_SERVICE_ACCOUNT_TOKEN>`_.