Skip to content

Commit b635213

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #209635 from maud-lv/ml-g-apikeys
Add Create API keys doc
2 parents bbe76b2 + 5a2a321 commit b635213

File tree

4 files changed

+143
-0
lines changed

4 files changed

+143
-0
lines changed

‎articles/managed-grafana/how-to-create-api-keys.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Create and manage Grafana API keys in Azure Managed Grafana
3+
description: Learn how to generate and manage Grafana API keys, and start making API calls for Azure Managed Grafana.
4+
author: maud-lv
5+
ms.author: malev
6+
ms.service: managed-grafana
7+
ms.topic: how-to
8+
ms.date: 08/31/2022
9+
---
10+
11+
# Generate and manage Grafana API keys in Azure Managed Grafana
12+
13+
In this guide, learn how to generate and manage API keys, and start making API calls to the Grafana server. Grafana API keys will enable you to create integrations between Azure Managed Grafana and other services.
14+
15+
## Prerequisites
16+
17+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free).
18+
- An Azure Managed Grafana instance. If you don't have one yet, [create an Azure Managed Grafana instance](./quickstart-managed-grafana-portal.md).
19+
20+
## Enable API keys
21+
22+
API keys are disabled by default in Azure Managed Grafana. You can enable this feature during the creation of the instance on the Azure portal, or you can activate it on an existing instance, using the Azure portal or the CLI.
23+
24+
### Create an Azure Managed Grafana workspace with API key creation enabled
25+
26+
During the creation of the Azure Managed Grafana workspace, enable the creation of API keys in the **Advanced** tab, by setting **Enable API key creation** to **Enabled**. For more information about creating a new instance using the Azure portal, go to [Quickstart: Create an Azure Managed Grafana instance](quickstart-managed-grafana-portal.md).
27+
28+
### Enable API key creation on an existing Azure Managed Grafana instance
29+
30+
#### [Portal](#tab/azure-portal)
31+
32+
1. In the Azure portal, under **Settings**, select **Configuration**, and then under **API keys**, select **Enable**.
33+
34+
:::image type="content" source="media/create-api-keys/enable-api-keys.png" alt-text="Screenshot of the Azure platform. Enable API keys.":::
35+
1. Select **Save** to confirm that you want to activate the creation of API keys in Azure Managed Grafana.
36+
37+
#### [Azure CLI](#tab/azure-cli)
38+
39+
Run the [az grafana update](/cli/azure/grafana#az-grafana-update) command to enable the creation of API keys in an existing Azure Managed Grafana instance. In the command below, replace `<azure-managed-grafana-name>` with the name of the Azure Managed Grafana instance to update.
40+
41+
```azurecli-interactive
42+
az grafana update --name <azure-managed-grafana-name> --api-keys Enabled
43+
```
44+
45+
---
46+
47+
## Generate an API key
48+
49+
### [Portal](#tab/azure-portal)
50+
51+
1. Open your Azure Managed Grafana instance and from the left menu, select **Configuration > API keys**.
52+
:::image type="content" source="media/create-api-keys/access-page.png" alt-text="Screenshot of the Grafana dashboard. Access API keys page.":::
53+
1. Select **New API key**.
54+
1. Fill out the form, and select **Add** to generate the new API key.
55+
56+
| Parameter | Description | Example |
57+
|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
58+
| **Key name** | Enter a name for your new Grafana API key. | *api-key-1* |
59+
| **Managed Grafana role** | Choose a Managed Grafana role: Viewer, Editor or Admin. | *Editor* |
60+
| **Time to live** | Enter a time before your API key expires. Use *s* for seconds, *m* for minutes, *h* for hours, *d* for days, *w* for weeks, *M* for months, *y* for years. | 7d |
61+
62+
:::image type="content" source="media/create-api-keys/form.png" alt-text="Screenshot of the Grafana dashboard. API creation form filled out.":::
63+
64+
1. Once the key has been generated, a message pops up with the new key and a curl command including your key. Copy this information and save it in your records now, as it will be hidden once you leave this page. If you close this page without save the new API key, you'll need to generate a new one.
65+
66+
:::image type="content" source="media/create-api-keys/api-key-created.png" alt-text="Screenshot of the Grafana dashboard. API key is displayed.":::
67+
68+
You can now use this Grafana API key to call the Grafana server.
69+
70+
### [Azure CLI](#tab/azure-cli)
71+
72+
1. Run the [az grafana api-key create](/cli/azure/grafana/api-key#az-grafana-api-key-create) command to create an API key for Azure Managed Grafana. Replace `<azure-managed-grafana-name>` and `<key>` with the name of the Azure Managed Grafana instance to update and a name for the new API key.
73+
74+
Optionally also add more parameters, such as `--role` and `--time-to-live`.
75+
76+
| Parameter | Description | Example |
77+
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
78+
| `--role` | Select an Azure Managed Grafana role by entering `Admin`, `Editor` or `Viewer`. The default value is `Viewer`. | *Editor* |
79+
| `--time-to-live` | Enter a time before your API key expires. Use `s` for seconds, `m` for minutes, `h` for hours, `d` for days, `w` for weeks, `M` for months or `y` for years. The default value is `1d`. | 7d |
80+
81+
```azurecli-interactive
82+
az grafana api-key create --name <azure-managed-grafana-name> --key <key>
83+
```
84+
85+
1. The terminal returns a key ID, a key and a key name. Copy this information and save it in your records now, as you'll only be able to view this key once.
86+
87+
---
88+
89+
## Test the API key
90+
91+
Run the [az grafana dashboard list](/cli/azure/grafana/dashboard#az-grafana-dashboard-list) command below to check if your API key is working. Replace the placeholders `<azure-managed-grafana-name>` and `<api-key>` with the name of your Azure Managed Grafana instance and your API key.
92+
93+
```azurecli-interactive
94+
az grafana dashboard list --name <azure-managed-grafana-name> --api-key <api-key>
95+
```
96+
97+
The terminal's output lists all the dashboards your API key can access in the specified Azure Managed Grafana instance.
98+
99+
## Manage API keys
100+
101+
### [Portal](#tab/azure-portal)
102+
103+
Existing API keys are listed in **Configuration > API keys**. By default, only active API keys are displayed. Select **Include expired keys** to view all created keys, and select **X** (Delete) to delete the API key.
104+
105+
:::image type="content" source="media/create-api-keys/manage.png" alt-text="Screenshot of the Grafana dashboard. API keys are listed under Configuration > API keys.":::
106+
107+
### [Azure CLI](#tab/azure-cli)
108+
109+
#### List API keys
110+
111+
Run the [az grafana api-key list](/cli/azure/grafana/api-key#az-grafana-api-key-list) command to list the API keys in an existing Azure Managed Grafana instance. In the command below, replace `<azure-managed-grafana-name>` with the name of the Azure Managed Grafana instance.
112+
113+
```azurecli-interactive
114+
az grafana api-key list --name <azure-managed-grafana-name> --output table
115+
```
116+
117+
Example of output:
118+
119+
```Output
120+
Name Role Expiration
121+
----- ------ --------------------
122+
key01 Viewer
123+
key02 Viewer 2022-08-31T17:14:44Z
124+
```
125+
126+
#### Delete API keys
127+
128+
Run the [az grafana api-key delete](/cli/azure/grafana/api-key#az-grafana-api-key-delete) command to delete API keys. In the command below, replace `<azure-managed-grafana-name>` and `<key>`with the name of the Azure Managed Grafana instance and the ID or the name of the API key to delete.
129+
130+
```azurecli-interactive
131+
az grafana api-key delete --name <azure-managed-grafana-name> --key <key>
132+
```
133+
134+
---
135+
136+
## Next steps
137+
138+
In this how-to guide, you learned how to create an API key for Azure Managed Grafana. To learn how to call Grafana APIs, see:
139+
140+
> [!div class="nextstepaction"]
141+
> [Call Grafana APIs](how-to-api-calls.md)

‎articles/managed-grafana/media/create-api-keys/api-key-created.png

-3.44 KB
Loading

‎articles/managed-grafana/media/create-api-keys/enable-api-keys.png

87.3 KB
Loading

‎articles/managed-grafana/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ items:
3737
href: how-to-share-grafana-workspace.md
3838
- name: Monitor a Managed Grafana instance
3939
href: how-to-monitor-managed-grafana-workspace.md
40+
- name: Create and manage API keys
41+
href: how-to-create-api-keys.md
4042
- name: Troubleshoot common issues
4143
href: troubleshoot-managed-grafana.md
4244
- name: Enable zone redundancy

0 commit comments

Comments
 (0)