Save GitHub tool connection¶

Save the GitHub tool connection for the current workspace. The access token in the request is only used to establish or update credentials, the token is not echoed on a successful response.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/tools/github/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/github/connect" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "<GITHUB_ACCESS_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
`access_token`	string	Yes	GitHub access token. Do not include the `Bearer` prefix. The token cannot contain leading or trailing whitespace, newlines, or path separators.

Successful response¶

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

Response example

JSON
{
  "code": 0,
  "data": {
    "tool_id": "moi.github.tools",
    "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	GitHub built-in tool identifier.
`data.credential_ref`	string	A reference to a saved credential, not an access token.
`data.status`	string	Connection status; new connection is `connected`.
`data.connected_at`	string	The time the connection was established, using RFC 3339 format.
`data.requires_reconnect`	boolean	Whether to reconnect; the new connection is `false`.

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 request body is invalid, or the access token is empty, contains the `Bearer` prefix, a newline, or disallowed characters.	Submit the token value itself and check the field 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`）	The GitHub tool connection service or authorization dependency is temporarily unavailable.	Try again later.

Follow-up operations¶

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

Last updated on Sep 15, 2026