Documentation

Grafana Cloud

Developer resources

HTTP API

Secrets Management HTTP API

Enterprise Grafana Cloud

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 for more information.

To view more about the new API structure, refer to API overview.

Caution
The API is currently in public preview and might be subject to changes.

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.

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 for a list of supported values.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:create`	`secret.securevalues:*`

Example create request:

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/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.

Query parameters

labelSelector: Filter secure values by labels.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:read`	`secret.securevalues:*`

Example list request:

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/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.
name: The name of the secure value.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:read`	`secret.securevalues:*`

Example get request:

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/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.
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 for a list of supported values.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:write`	`secret.securevalues:*`

Example update request:

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/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.
name: The name of the secure value.

Required permissions

See note in the introduction for an explanation.

Action	Scope
`secret.securevalues:delete`	`secret.securevalues:*`

Example delete request:

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/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 65

{
  "apiVersion": "v1",
  "kind": "Status",
  "status": "Success",
  "code": 200
}

Status Codes: