From a72b557886bdc6644d07781e50e056e60158a15a Mon Sep 17 00:00:00 2001 From: Ieva Date: Thu, 29 Aug 2024 10:50:11 +0100 Subject: [PATCH] Docs: Extend docs with service account limitations (#92630) * extend docs with service account limitations * linting * Apply suggestions from code review Co-authored-by: Jack Baldry * PR feedback * more PR feedback * linting --------- Co-authored-by: Jack Baldry --- .../administration/service-accounts/index.md | 2 ++ docs/sources/developers/http_api/admin.md | 12 +++++++++--- docs/sources/developers/http_api/licensing.md | 10 ++++++++++ docs/sources/developers/http_api/org.md | 14 +++++++++----- docs/sources/developers/http_api/user.md | 14 ++++++++++---- 5 files changed, 40 insertions(+), 12 deletions(-) diff --git a/docs/sources/administration/service-accounts/index.md b/docs/sources/administration/service-accounts/index.md index 70010b2defe..ff6971f2096 100644 --- a/docs/sources/administration/service-accounts/index.md +++ b/docs/sources/administration/service-accounts/index.md @@ -37,6 +37,8 @@ In [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) {{% admonition type="note" %}} Service accounts can only act in the organization they are created for. If you have the same task that is needed for multiple organizations, we recommend creating service accounts in each organization. + +Service accounts can't be used for instance-wide operations, such as global user management and organization management. For these tasks, you need to use a user with [Grafana server administrator permissions]({{< relref "../roles-and-permissions/#grafana-server-administrators" >}}). {{% /admonition %}} {{< vimeo 742056367 >}} diff --git a/docs/sources/developers/http_api/admin.md b/docs/sources/developers/http_api/admin.md index b8d88c4e90d..eb96ebecf95 100644 --- a/docs/sources/developers/http_api/admin.md +++ b/docs/sources/developers/http_api/admin.md @@ -18,9 +18,15 @@ title: 'Admin HTTP API ' # Admin API -The Admin HTTP API does not currently work with an API Token. API Tokens are currently only linked to an organization and an organization role. They cannot be given -the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user -must have the Grafana Admin permission. (The default admin user is called `admin` and has permission to use this API.) +{{< admonition type="caution" >}} +You can't authenticate to the Admin HTTP API with service account tokens. +Service accounts are limited to an organization and an organization role. +They can't be granted [Grafana server administrator permissions](/docs/grafana//administration/roles-and-permissions/#grafana-server-administrators). + +To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission. + +The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints. +{{< /admonition >}} > If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/" >}}) for more information. diff --git a/docs/sources/developers/http_api/licensing.md b/docs/sources/developers/http_api/licensing.md index a248fddc8cc..937f25a8468 100644 --- a/docs/sources/developers/http_api/licensing.md +++ b/docs/sources/developers/http_api/licensing.md @@ -21,6 +21,16 @@ title: Licensing HTTP API Licensing is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "/docs/grafana/latest/introduction/grafana-enterprise" >}}). +{{< admonition type="caution" >}} +You can't authenticate to the Licensing HTTP API with service account tokens. +Service accounts are limited to an organization and an organization role. +They can't be granted [Grafana server administrator permissions](/docs/grafana//administration/roles-and-permissions/#grafana-server-administrators). + +To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission. + +The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints. +{{< /admonition >}} + > If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information. ## Check license availability diff --git a/docs/sources/developers/http_api/org.md b/docs/sources/developers/http_api/org.md index c83f5a84c4b..d79a60f95ef 100644 --- a/docs/sources/developers/http_api/org.md +++ b/docs/sources/developers/http_api/org.md @@ -282,11 +282,15 @@ Content-Type: application/json ## Admin Organizations API -The Admin Organizations HTTP API does not currently work with an API Token. API Tokens are currently -only linked to an organization and an organization role. They cannot be given the permission of server -admin, only users can be given that permission. So in order to use these API calls you will have to -use Basic Auth and the Grafana user must have the Grafana Admin permission (The default admin user -is called `admin` and has permission to use this API). +{{< admonition type="caution" >}} +You can't authenticate to the Admin Organizations HTTP API with service account tokens. +Service accounts are limited to an organization and an organization role. +They can't be granted [Grafana server administrator permissions](/docs/grafana//administration/roles-and-permissions/#grafana-server-administrators). + +To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission. + +The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints. +{{< /admonition >}} ### Get Organization by Id diff --git a/docs/sources/developers/http_api/user.md b/docs/sources/developers/http_api/user.md index 428c12c3472..bde419c26b5 100644 --- a/docs/sources/developers/http_api/user.md +++ b/docs/sources/developers/http_api/user.md @@ -24,11 +24,17 @@ refs: # User API -The Users HTTP API does not currently work with an API Token. API Tokens are linked to an organization and an organization role. They cannot be given -the permission of server users access, only users can be given that permission. To use these API calls you can use Basic Auth and the Grafana -user must have the Grafana Admin role. +{{< admonition type="caution" >}} +You can't authenticate to the User HTTP API with service account tokens. +Service accounts are limited to an organization and an organization role. +They can't be granted [Grafana server administrator permissions](/docs/grafana//administration/roles-and-permissions/#grafana-server-administrators). -API Tokens can be used with Organization HTTP API to get users of specific organization. +Alternatively, you can use the [Organization HTTP API](/docs/grafana//developers/http_api/org/#current-organization-api) with service account tokens to manage users in a specific organization + +To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission. + +The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints. +{{< /admonition >}} > If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](ref:role-based-access-control-permissions) for more information.