Save Grafana tool connection¶

Save the Grafana tool connection for the current workspace. The service account token is only used to create or update credentials, and the token will not be echoed in a successful response.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/tools/grafana/connect

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/tools/grafana/connect" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "grafana_url": "https://grafana.example.com",
    "service_account_token": "<SERVICE_ACCOUNT_TOKEN>"
  }'

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	The current workspace ID.

Request body

Field	Type	Is it required	Description
`grafana_url`	string	Yes	Grafana base URL, protocol can only be `http` or `https`; cannot contain credentials, query parameters, fragments, or paths ending in `/api`.
`service_account_token`	string	Yes	The Grafana service account token itself. Do not include the `Bearer` prefix, nor whitespace characters or path separators.

Successful response¶

Returns 200 on success. Reconnecting updates the Grafana connection in the workspace.

Response example

JSON
{
  "code": 0,
  "data": {
    "tool_id": "moi.grafana.tools",
    "grafana_url": "https://grafana.example.com",
    "credential_ref": "cred_01",
    "status": "connected",
    "connected_at": "2026-01-02T15:04:05Z",
    "requires_reconnect": false
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.tool_id`	string	Grafana built-in tool identifier.
`data.grafana_url`	string	The saved Grafana base URL.
`data.credential_ref`	string	A reference to a saved credential, not a service account token.
`data.status`	string	Connection status and whether reconnection is required.
`data.requires_reconnect`	boolean	Connection status and whether reconnection is required.
`data.connected_at`	string	The time the connection was established, using RFC 3339 format.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "<错误信息>"
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The URL, service account token, or request body is invalid.	Use Grafana base URL without credentials and `/api` suffix, and check the token format.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to manage tool connections in the workspace.	Check workspace authorization.
`503`	`15`（`UNAVAILABLE`）	Grafana tool connection service or authorization dependency is temporarily unavailable.	Try again later.

Follow-up operations¶

After saving, Query Grafana tool connection confirms the connection configuration.

Last updated on Sep 15, 2026