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

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools/github/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/github/connect" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "<GITHUB_ACCESS_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 |
| --- | --- | --- | --- |
| `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.

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

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

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