mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
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
This commit is contained in:
Ieva
GitHub
parent
e67485de30
commit
9c47161c14
@ -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 <your service account token>`.
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
@ -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 <your api key>`.
|
||||
|
||||
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`
|
||||
|
||||
|
||||
@ -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/<id of new org>
|
||||
```
|
||||
|
||||
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/<service account id>/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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user