--- title: "Secrets Management HTTP API | Grafana Cloud documentation" description: "Grafana Secrets Management HTTP API" --- # Secrets Management API > Note > > Available in Grafana 12 and later. > > This API complies with the new Grafana API structure. To learn more refer to documentation about the [API structure in Grafana](/docs/grafana-cloud/developer-resources/api-reference/http-api/apis/). The Grafana Secrets Management API allows you to manage secrets that are used by other services and applications within your Grafana instance. > Caution > > The API is currently in [public preview](/docs/release-life-cycle/#public-preview) and might be subject to changes. ## Requirements If you’re running Grafana Enterprise, you’ll need to have specific permissions for some endpoints. Refer to [Role-based access control permissions](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/custom-role-actions-scopes/) for more information. ## 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: - `k6-cloud` (for Grafana Cloud k6) - `provisioning.grafana.app` (for GitSync/Provisioning) - `synthetic-monitoring` (for Synthetic Monitoring checks) ## 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](/docs/grafana-cloud/developer-resources/api-reference/http-api/apis/). **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. Expand table ActionScope `secret.securevalues:create` - `secret.securevalues:*` **Example create request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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) > Note > > The `spec.value` field is never returned by API endpoints. Users cannot not decrypt secrets. ## 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](/docs/grafana-cloud/developer-resources/api-reference/http-api/apis/). **Query parameters** - `labelSelector`: Filter secure values by labels. **Required permissions** See note in the [introduction](#secrets-management-api) for an explanation. Expand table ActionScope `secret.securevalues:read` - `secret.securevalues:*` **Example list request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](/docs/grafana-cloud/developer-resources/api-reference/http-api/apis/). - `name`: The name of the secure value. **Required permissions** See note in the [introduction](#secrets-management-api) for an explanation. Expand table ActionScope `secret.securevalues:read` - `secret.securevalues:*` **Example get request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](/docs/grafana-cloud/developer-resources/api-reference/http-api/apis/). - `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. Expand table ActionScope `secret.securevalues:write` - `secret.securevalues:*` **Example update request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](/docs/grafana-cloud/developer-resources/api-reference/http-api/apis/). - `name`: The name of the secure value. **Required permissions** See note in the [introduction](#secrets-management-api) for an explanation. Expand table ActionScope `secret.securevalues:delete` - `secret.securevalues:*` **Example delete request**: http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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