From 8e40f581efe218f7bc588ef1a5cc582fcd9d1943 Mon Sep 17 00:00:00 2001 From: "grafana-delivery-bot[bot]" <132647405+grafana-delivery-bot[bot]@users.noreply.github.com> Date: Tue, 18 Nov 2025 17:52:33 +0000 Subject: [PATCH] [release-12.2.2] Docs: Add secrets management beta API docs (#114115) Co-authored-by: Matheus Macabu Co-authored-by: Anna Urbiztondo Co-authored-by: Jacob Valdez --- .../custom-role-actions-scopes/index.md | 4 + .../api-reference/http-api/_index.md | 1 + .../http-api/secrets_management.md | 401 ++++++++++++++++++ 3 files changed, 406 insertions(+) create mode 100644 docs/sources/developer-resources/api-reference/http-api/secrets_management.md diff --git a/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md b/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md index 31aeaa1a99a..13b73cca4d3 100644 --- a/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md +++ b/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md @@ -140,6 +140,10 @@ The following list contains role-based access control actions. | `roles:read` |
  • `roles:*`
  • `roles:uid:*`
| List roles and read a specific role with its permissions. | | `roles:write` |
  • `permissions:type:delegate`
      • | Create or update a custom role. | | `roles:write` |
      • `permissions:type:escalate`
          • | Reset basic roles to their default permissions. | +| `secret.securevalues:create` |
          • `secret.securevalues:*`
          • | Create secure values. | +| `secret.securevalues:read` |
            • `secret.securevalues:*`
            • | Read and list secure values. | +| `secret.securevalues:write` |
              • `secret.securevalues:*`
              • | Update secure values. | +| `secret.securevalues:delete` |
                • `secret.securevalues:*`
                • | Delete secure values. | | `server.stats:read` | None | Read Grafana instance statistics. | | `server.usagestats.report:read` | None | View usage statistics report. | | `serviceaccounts:write` |
                  • `serviceaccounts:*`
                      • | Create Grafana service accounts. | diff --git a/docs/sources/developer-resources/api-reference/http-api/_index.md b/docs/sources/developer-resources/api-reference/http-api/_index.md index 7d45c435832..39818bd4185 100644 --- a/docs/sources/developer-resources/api-reference/http-api/_index.md +++ b/docs/sources/developer-resources/api-reference/http-api/_index.md @@ -98,6 +98,7 @@ Grafana Enterprise includes all of the Grafana OSS APIs as well as the following - [Query and resource caching API](query_and_resource_caching/) - [Reporting API](reporting/) - [Role-based access control API](access_control/) +- [Secrets Management API](secrets_management/) - [Team sync API](team_sync/) ## Deprecated HTTP APIs diff --git a/docs/sources/developer-resources/api-reference/http-api/secrets_management.md b/docs/sources/developer-resources/api-reference/http-api/secrets_management.md new file mode 100644 index 00000000000..7dc7edcec3c --- /dev/null +++ b/docs/sources/developer-resources/api-reference/http-api/secrets_management.md @@ -0,0 +1,401 @@ +--- +aliases: + - ../../../http_api/secrets_management/ # /docs/grafana/next/http_api/secrets_management/ + - ../../../developers/http_api/secrets_management/ # /docs/grafana/next/developers/http_api/secrets_management/ +canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/secrets_management/ +description: Grafana Secrets Management HTTP API +keywords: + - grafana + - http + - documentation + - api + - secrets + - enterprise +labels: + products: + - enterprise + - cloud +title: Secrets Management HTTP API +refs: + api-overview: + - pattern: /docs/grafana/ + destination: /docs/grafana//developers/http_api/apis/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/apis/ + rbac-permissions: + - pattern: /docs/grafana/ + destination: /docs/grafana//administration/roles-and-permissions/access-control/custom-role-actions-scopes/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/custom-role-actions-scopes/ +--- + +# Secrets Management API + +> If you are running Grafana Enterprise, you need to have specific permissions for some endpoints . Refer to [Role-based access control permissions](ref:rbac-permissions) for more information. + +> To view more about the new API structure, refer to [API overview](ref:api-overview). + +{{< admonition type="caution" >}} +The API is currently in [public preview](https://grafana.com/docs/release-life-cycle/#public-preview) and might be subject to changes. +{{< /admonition >}} + +The Grafana Secrets Management API allows you to manage secrets that are used by other services and applications within your Grafana instance. + +### Decrypters + +The decrypters field is an allowlist that lets the secure value know which services and apps can decrypt the secret value. + +Currently available decrypters: + +- `synthetic-monitoring` (for Synthetic Monitoring checks) +- `provisioning.grafana.app` (for GitSync/Provisioning) + +## Create a secure value + +`POST /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues` + +Creates a new secure value. + +**URL parameters** + +- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview). + +**Request body** + +- `metadata.name`: The Grafana unique identifier. If you do not want to provide this, set `metadata.generateName` instead to the prefix you would like for the randomly generated uid (can't be an empty string). +- `spec.description`: Short description that explains the purpose of this secure value. Required. Up to 25 characters long. +- `spec.value`: The secret value to store. Required. Up to 24576 bytes long. +- `spec.decrypters`: List of services allowed to decrypt this secure value. Up to 64 items, see note in [decrypters](#decrypters) for a list of supported values. + +**Required permissions** + +See note in the [introduction](#secrets-management-api) for an explanation. + + +| Action | Scope | +| ---------------------------- | ----------------------------------------- | +| `secret.securevalues:create` |
                      • `secret.securevalues:*`
                      | +{ .no-spacing-list } + + +**Example create request**: + +```http +POST /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +{ + "metadata": { + "name": "api-key" + }, + "spec": { + "description": "External API Key", + "value": "secret-api-key-12345", + "decrypters": ["synthetic-monitoring"] + } +} +``` + +**Example response**: + +```http +HTTP/1.1 201 Created +Content-Type: application/json; charset=UTF-8 +Content-Length: 343 + +{ + "apiVersion": "secret.grafana.app/v1beta1", + "kind": "SecureValue", + "metadata": { + "name": "api-key", + "namespace": "default", + "uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "creationTimestamp": "2024-01-15T10:35:00Z" + }, + "spec": { + "description": "External API Key", + "decrypters": ["synthetic-monitoring"] + }, + "status": {} +} +``` + +Status Codes: + +- **201** – Created +- **400** – Errors (invalid JSON, missing or invalid fields, etc) +- **401** – Unauthorized +- **403** – Access denied +- **409** – Conflict (secure value with the same name already exists) + +{{< admonition type="note">}} +The `spec.value` field is never returned by API endpoints. Users cannot not decrypt secrets. +{{< /admonition >}} + +## List secure values + +`GET /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues` + +List all secure values in a namespace. + +**URL parameters** + +- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview). + +**Query parameters** + +- `labelSelector`: Filter secure values by labels. + +**Required permissions** + +See note in the [introduction](#secrets-management-api) for an explanation. + + +| Action | Scope | +| ---------------------------- | ----------------------------------------- | +| `secret.securevalues:read` |
                      • `secret.securevalues:*`
                      | +{ .no-spacing-list } + + +**Example list request**: + +```http +GET /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + +**Example response**: + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +Content-Length: 383 + +{ + "apiVersion": "secret.grafana.app/v1beta1", + "kind": "SecureValueList", + "metadata": { + "resourceVersion": "12345" + }, + "items": [ + { + "apiVersion": "secret.grafana.app/v1beta1", + "kind": "SecureValue", + "metadata": { + "name": "database-password", + "namespace": "default", + "creationTimestamp": "2024-01-15T10:30:00Z" + }, + "spec": { + "description": "Production DB Password", + "decrypters": ["synthetic-monitoring"] + }, + "status": {} + } + ] +} +``` + +Status Codes: + +- **200** – OK +- **401** – Unauthorized +- **403** – Access denied + +## Get a secure value + +`GET /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name` + +Get the details of a specific secure value. It will not return the secret value. + +**URL parameters** + +- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview). +- `name`: The name of the secure value. + +**Required permissions** + +See note in the [introduction](#secrets-management-api) for an explanation. + + +| Action | Scope | +| ---------------------------- | ----------------------------------------- | +| `secret.securevalues:read` |
                      • `secret.securevalues:*`
                      | +{ .no-spacing-list } + + +**Example get request**: + +```http +GET /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + +**Example response**: + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +Content-Length: 294 + +{ + "apiVersion": "secret.grafana.app/v1beta1", + "kind": "SecureValue", + "metadata": { + "name": "api-key", + "namespace": "default", + "uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "creationTimestamp": "2024-01-15T10:35:00Z" + }, + "spec": { + "description": "External API Key", + "decrypters": ["synthetic-monitoring"] + }, + "status": {} +} +``` + +Status Codes: + +- **200** – OK +- **401** – Unauthorized +- **403** – Access denied +- **404** – Not found + +## Update a secure value + +`PUT /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name` + +Replace an existing secure value with a new specification. + +**URL parameters** + +- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview). +- `name`: The name of the secure value. + +**Request body** + +- `spec.description`: Short description that explains the purpose of this secure value. Required. Up to 25 characters long. +- `spec.value`: The secret value to store. Required. Up to 24576 bytes long. +- `spec.decrypters`: List of services allowed to decrypt this secure value. Up to 64 items, see note in [decrypters](#decrypters) for a list of supported values. + +**Required permissions** + +See note in the [introduction](#secrets-management-api) for an explanation. + + +| Action | Scope | +| --------------------------- | ----------------------------------------- | +| `secret.securevalues:write` |
                      • `secret.securevalues:*`
                      | +{ .no-spacing-list } + + +**Example update request**: + +```http +PUT /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +{ + "metadata": { + "name": "api-key" + }, + "spec": { + "description": "External API Key", + "value": "new-value-12345", + "decrypters": ["synthetic-monitoring"] + } +} +``` + +**Example response**: + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +Content-Length: 282 + +{ + "apiVersion": "secret.grafana.app/v1beta1", + "kind": "SecureValue", + "metadata": { + "name": "api-key", + "namespace": "default", + "uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "creationTimestamp": "2024-01-15T10:35:00Z" + }, + "spec": { + "description": "External API Key", + "decrypters": ["synthetic-monitoring"] + } +} +``` + +Status Codes: + +- **200** – OK +- **400** – Errors (invalid JSON, missing or invalid fields, etc) +- **401** – Unauthorized +- **403** – Access denied +- **404** – Not found + +## Delete a secure value + +`DELETE /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name` + +Permanently delete a secure value. This also deletes the underlying stored secret value. + +**URL parameters** + +- `namespace`: To read more about the namespace to use, see the [API overview](ref:api-overview). +- `name`: The name of the secure value. + +**Required permissions** + +See note in the [introduction](#secrets-management-api) for an explanation. + + +| Action | Scope | +| ---------------------------- | ----------------------------------------- | +| `secret.securevalues:delete` |
                      • `secret.securevalues:*`
                      | +{ .no-spacing-list } + + +**Example delete request**: + +```http +DELETE /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + +**Example response**: + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +Content-Length: 65 + +{ + "apiVersion": "v1", + "kind": "Status", + "status": "Success", + "code": 200 +} +``` + +Status Codes: + +- **200** – OK +- **401** – Unauthorized +- **403** – Access denied +- **404** – Not found