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

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools/grafana/connect
```

## Before you call

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: The workspace ID to save the connection, passed through the `X-Workspace-ID` Header.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/tools/grafana/connect" \
  -H "X-API-Key: $AI_STUDIO_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>"
  }'
```

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

```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
  }
}
```

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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](get-grafana-connection.md) confirms the connection configuration.