diff --git a/docs/sources/developers/http_api/_index.md b/docs/sources/developers/http_api/_index.md index 28ec50df492..a37489074de 100644 --- 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 `. +{{< docs/shared lookup="developers/authentication.md" source="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/" >}}) diff --git a/docs/sources/developers/http_api/authentication.md b/docs/sources/developers/http_api/authentication.md new file mode 100644 index 00000000000..55b5bc46bf3 --- /dev/null +++ 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="" >}} diff --git a/docs/sources/developers/http_api/examples/_index.md b/docs/sources/developers/http_api/examples/_index.md new file mode 100644 index 00000000000..6fd3810eaed --- /dev/null +++ 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 >}} diff --git a/docs/sources/developers/http_api/create-api-tokens-for-org.md b/docs/sources/developers/http_api/examples/create-api-tokens-for-org.md similarity index 92% rename from docs/sources/developers/http_api/create-api-tokens-for-org.md rename to docs/sources/developers/http_api/examples/create-api-tokens-for-org.md index aa047898da2..d5b2ded16a4 100644 --- a/docs/sources/developers/http_api/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//http_api/create-api-tokens-for-org/ + - ../../../tutorials/api_org_token_howto/ # /docs/grafana//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 diff --git a/docs/sources/developers/http_api/curl-examples.md b/docs/sources/developers/http_api/examples/curl-examples.md similarity index 83% rename from docs/sources/developers/http_api/curl-examples.md rename to docs/sources/developers/http_api/examples/curl-examples.md index bea3d4e702d..a7f3c1ca2e8 100644 --- a/docs/sources/developers/http_api/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//http_api/curl-examples/ + - ../../http_api/curl-examples/ # /docs/grafana//developers/http_api/curl-examples/ +canonical: /docs/grafana/latest/developers/http_api/examples/curl-examples/ description: cURL examples keywords: - grafana diff --git a/docs/sources/shared/developers/authentication.md b/docs/sources/shared/developers/authentication.md new file mode 100644 index 00000000000..6e5158dc46f --- /dev/null +++ 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 `_.