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>
2025-08-02 06:52:13 +08:00 · 2024-09-06 08:17:20 +02:00
parent d8c3645f31
commit e87140bf75
6 changed files with 87 additions and 39 deletions
--- a/docs/sources/developers/http_api/_index.md
+++ b/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).
-
-### 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>`.
+{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}

 ## 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/" >}})
--- a/docs/sources/developers/http_api/authentication.md
+++ b/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>" >}}
--- a/docs/sources/developers/http_api/examples/_index.md
+++ b/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 >}}
--- a/docs/sources/developers/http_api/examples/create-api-tokens-for-org.md
+++ b/docs/sources/developers/http_api/examples/create-api-tokens-for-org.md
@ -1,8 +1,8 @@
 ---
 aliases:
-  - ../../http_api/create-api-tokens-for-org/
-  - ../../tutorials/api_org_token_howto/
-canonical: /docs/grafana/latest/developers/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/ # /docs/grafana/<GRAFANA_VERSION>/tutorials/api_org_token_howto/
+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
--- a/docs/sources/developers/http_api/examples/curl-examples.md
+++ b/docs/sources/developers/http_api/examples/curl-examples.md
@ -1,7 +1,8 @@
 ---
 aliases:
-  - ../../http_api/curl-examples/
-canonical: /docs/grafana/latest/developers/http_api/curl-examples/
+  - ../../../http_api/curl-examples/ # /docs/grafana/<GRAFANA_VERSION>/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
--- a/docs/sources/shared/developers/authentication.md
+++ b/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>`_.