From 1fdec630d94ac9ddf12982ce982ff9f783b26a9d Mon Sep 17 00:00:00 2001
From: Witold Duranek <contact@witalis.net>
Date: Fri, 22 Mar 2024 12:39:09 +0100
Subject: [PATCH] feat: add netdata cloud api-tokens docs (#17225)

* feat: add netdata cloud api-tokens docs

* Update api-tokens.md

* Update api-tokens.md

* move to netadata-cloud/

* Update api-tokens.md

---------

Co-authored-by: Fotis Voutsas <fotis@netdata.cloud>
---
 docs/netdata-cloud/api-tokens.md | 34 ++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 docs/netdata-cloud/api-tokens.md

diff --git a/docs/netdata-cloud/api-tokens.md b/docs/netdata-cloud/api-tokens.md
new file mode 100644
index 0000000000..1b700ba4b5
--- /dev/null
+++ b/docs/netdata-cloud/api-tokens.md
@@ -0,0 +1,34 @@
+# API Tokens
+
+## Overview
+
+Every single user can get access to the Netdata resource programmatically. It is done through the API Token which
+can be also called as Bearer Token. This token is used for authentication and authorization, it can be issued
+in the Netdata UI under the user Settings:
+
+<img width="316" alt="image" src="https://github.com/netdata/netdata/assets/14999928/b0846076-afae-47ab-92df-c24967305ab9">
+
+The API Tokens are not going to expire and can be limited to a few scopes:
+
+* `scope:all`
+
+  this token is given the same level of action as the user has, the use-case for it is Netdata terraform provider
+
+* `scope:agent-ui`
+
+  this token is mainly used by the local Netdata agent accessing the Cloud UI
+
+* `scope:grafana-plugin`
+
+  this token is used for the [Netdata Grafana plugin](https://github.com/netdata/netdata-grafana-datasource-plugin/blob/master/README.md)
+  to access Netdata charts
+
+Currently, the Netdata Cloud is not exposing stable API.
+
+## Example usage
+
+* get the cloud space list
+
+```console
+$ curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/spaces
+```