From 9c47161c14636b4ab5dead9f2294e79d606d16b9 Mon Sep 17 00:00:00 2001 From: Ieva Date: Tue, 31 Oct 2023 13:29:08 +0000 Subject: [PATCH] Docs: deprecate API key reference docs and update API tutorial to use service accounts (#77429) * deprecate API key reference docs and update API tutorial to use service accounts * Update create-api-tokens-for-org.md --- docs/sources/developers/http_api/_index.md | 49 ++++++++++++- docs/sources/developers/http_api/auth.md | 71 ++----------------- .../http_api/create-api-tokens-for-org.md | 31 ++++++-- 3 files changed, 79 insertions(+), 72 deletions(-) diff --git a/docs/sources/developers/http_api/_index.md b/docs/sources/developers/http_api/_index.md index 81d8b851f43..aa01c6d1886 100644 --- a/docs/sources/developers/http_api/_index.md +++ b/docs/sources/developers/http_api/_index.md @@ -29,13 +29,59 @@ Starting from version 9.1, there is also a [OpenAPI v3 specification](https://ed Users can browser and try out both via the Swagger UI editor (served by the grafana server) by navigating to `/swagger-ui` and `/openapi3` respectively. +## Authenticating 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, and 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 `. + +## X-Grafana-Org-Id Header + +**X-Grafana-Org-Id** is an optional property that specifies the organization to which the action is applied. If it is not set, the created key belongs to the current context org. Use this header in all requests except those regarding admin. + +**Example Request**: + +```http +GET /api/org/ HTTP/1.1 +Accept: application/json +Content-Type: application/json +X-Grafana-Org-Id: 2 +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + ## HTTP APIs - [Admin API]({{< relref "admin/" >}}) - [Alerting API (unstable)](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/pkg/services/ngalert/api/tooling/post.json) - [Alerting Provisioning API]({{< relref "alerting_provisioning/" >}}) - [Annotations API]({{< relref "annotations/" >}}) -- [Authentication API]({{< relref "auth/" >}}) - [Correlations API]({{< relref "correlations/" >}}) - [Dashboard API]({{< relref "dashboard/" >}}) - [Dashboard Permissions API]({{< relref "dashboard_permissions/" >}}) @@ -59,6 +105,7 @@ Users can browser and try out both via the Swagger UI editor (served by the graf - [Alerting Notification Channels API]({{< relref "alerting_notification_channels/" >}}) - [Alerting API]({{< relref "alerting/" >}}) +- [Authentication API]({{< relref "auth/" >}}) ## Grafana Enterprise HTTP APIs diff --git a/docs/sources/developers/http_api/auth.md b/docs/sources/developers/http_api/auth.md index e5db624f239..dfa53b051d9 100644 --- a/docs/sources/developers/http_api/auth.md +++ b/docs/sources/developers/http_api/auth.md @@ -19,72 +19,15 @@ title: 'Authentication HTTP API ' # Authentication API +The Authentication HTTP API is used to manage API keys. + +{{% admonition type="note" %}} +If you use Grafana v9.1 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service account API reference]({{< relref "./serviceaccount/" >}}). +{{% /admonition %}} + > If you are running Grafana Enterprise, for some endpoints you would need to have relevant permissions. Refer to [Role-based access control permissions]({{< relref "../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/" >}}) for more information. -## Tokens - -Currently, you can authenticate via an `API Token` or via a `Session cookie` (acquired using regular login or OAuth). - -## X-Grafana-Org-Id Header - -**X-Grafana-Org-Id** is an optional property that specifies the organization to which the action is applied. If it is not set, the created key belongs to the current context org. Use this header in all requests except those regarding admin. - -**Example Request**: - -```http -POST /api/auth/keys HTTP/1.1 -Accept: application/json -Content-Type: application/json -X-Grafana-Org-Id: 2 -Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - -{ - "name": "mykey", - "role": "Admin", - "secondsToLive": 86400 -} -``` - -## 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."} -``` - -## Create API Token - -Open the sidemenu and click the organization dropdown and select the `API Keys` option. - -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 `. - -The API Token can also be passed as a Basic authorization password with the special username `api_key`: - -curl example: - -```bash -curl http://api_key:eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk@localhost:3000/api/org -{"id":1,"name":"Main Org."} -``` - -# Auth HTTP resources / actions - -## Api Keys +## List API keys `GET /api/auth/keys` diff --git a/docs/sources/developers/http_api/create-api-tokens-for-org.md b/docs/sources/developers/http_api/create-api-tokens-for-org.md index 1e3a1ebeb18..aa047898da2 100644 --- a/docs/sources/developers/http_api/create-api-tokens-for-org.md +++ b/docs/sources/developers/http_api/create-api-tokens-for-org.md @@ -14,11 +14,11 @@ labels: products: - enterprise - oss -title: 'API Tutorial: Create API tokens and dashboards for an organization' +title: 'API Tutorial: Create Service Account tokens and dashboards for an organization' weight: 150 --- -# Create API tokens and dashboards for an organization +# Create Service Account tokens and dashboards for an organization Use the Grafana API to set up new Grafana organizations or to add dynamically generated dashboards to an existing organization. @@ -27,9 +27,9 @@ Use the Grafana API to set up new Grafana organizations or to add dynamically ge There are two authentication methods to access the API: - Basic authentication: A Grafana Admin user can access some parts of the Grafana API through basic authentication. -- API Tokens: All organization actions are accessed through an API Token. An API Token is associated with an organization. It can be used to create dashboards and other components specific for that organization. +- Service Account tokens: All organization actions can be accessed through a Service Account token. A Service Account token is associated with an organization. It can be used to create dashboards and other components specific for that organization. -## How to create a new organization and an API Token +## How to create a new organization and a Service Account Token The task is to create a new organization and then add a Token that can be used by other users. In the examples below which use basic auth, the user is `admin` and the password is `admin`. @@ -53,13 +53,30 @@ The task is to create a new organization and then add a Token that can be used b curl -X POST http://admin:admin@localhost:3000/api/user/using/ ``` -1. [Create the API token](http://docs.grafana.org/http_api/auth/#create-api-key): +1. [Create a Service Account]({{< relref "./serviceaccount/#create-service-account" >}}): ```bash - curl -X POST -H "Content-Type: application/json" -d '{"name":"apikeycurl", "role": "Admin"}' http://admin:admin@localhost:3000/api/auth/keys + curl -X POST -H "Content-Type: application/json" -d '{"name":"test", "role": "Admin"}' http://admin:admin@localhost:3000/api/serviceaccounts ``` - This should return a response: `{"name":"apikeycurl","key":"eyJrIjoiR0ZXZmt1UFc0OEpIOGN5RWdUalBJTllUTk83VlhtVGwiLCJuIjoiYXBpa2V5Y3VybCIsImlkIjo2fQ=="}`. +1. [Create a Service Account token]({{< relref "./serviceaccount/#create-service-account-tokens" >}}) for the service account created in the previous step: + + ```bash + curl -X POST -H "Content-Type: application/json" -d '{"name":"test-token"}' http://admin:admin@localhost:3000/api/serviceaccounts//tokens + ``` + + This should return a response: + + ```http + HTTP/1.1 200 + Content-Type: application/json + + { + "id": 7, + "name": "test-token", + "key": "eyJrIjoiVjFxTHZ6dGdPSjg5Um92MjN1RlhjMkNqYkZUbm9jYkwiLCJuIjoiZ3JhZmFuYSIsImlkIjoxfQ==" + } + ``` Save the key returned here in your password manager as it is not possible to fetch again it in the future.