> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Github

> Validate and store a GitHub personal access token. Enables repository access for agent tasks. Replaces any previously stored token.

This endpoint validates a GitHub personal access token against the GitHub API and stores it for future agent tasks. If a token is already stored, it is replaced.

<Note>
  This endpoint requires a **Pro subscription**. Required GitHub token scopes: `repo` (for private repos) and `user` (for profile info).
</Note>

## Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

1. Go to [app.blackbox.ai/agent-api](https://app.blackbox.ai/agent-api) and click **Get an API Key** (requires a Pro subscription)
2. Once provisioning completes, you will be redirected to your [Dashboard](https://app.blackbox.ai/dashboard)
3. From the Dashboard, create an API key to use with all Agent API requests

Your API key will be in the format: `sk-xxxxxxxxxxxxxxxxxxxxxx`

## Headers

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request Body

<ParamField body="githubToken" type="string" required>
  A GitHub personal access token (classic or fine-grained).

  Example: `"ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"`
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  `true` when the token was validated and stored successfully.
</ResponseField>

<ResponseField name="login" type="string">
  GitHub username confirmed by the token.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X POST 'https://agent.blackbox.ai/api/v1/git/config' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{ "githubToken": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const API_KEY = "YOUR_API_KEY";

  const response = await fetch(
    "https://agent.blackbox.ai/api/v1/git/config",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ githubToken: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }),
    }
  );
  const data = await response.json();
  console.log(`Stored token for: ${data.login}`);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  API_KEY = "YOUR_API_KEY"

  response = requests.post(
      "https://agent.blackbox.ai/api/v1/git/config",
      headers={
          "Authorization": f"Bearer {API_KEY}",
          "Content-Type": "application/json",
      },
      json={"githubToken": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
  )
  data = response.json()
  print(f"Stored token for: {data['login']}")
  ```

  ```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      apiKey := "YOUR_API_KEY"
      url := "https://agent.blackbox.ai/api/v1/git/config"

      body, _ := json.Marshal(map[string]string{
          "githubToken": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      })

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer "+apiKey)
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      respBody, _ := io.ReadAll(resp.Body)
      var result map[string]interface{}
      json.Unmarshal(respBody, &result)
      fmt.Printf("Stored token for: %s\n", result["login"])
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "success": true,
    "login": "octocat"
  }
  ```

  ```json Error - Invalid Token theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Invalid GitHub token: authentication failed"
  }
  ```

  ```json Error - Missing Token theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "githubToken is required"
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error                 | Description                                       |
| ----------- | --------------------- | ------------------------------------------------- |
| 200         | Success               | Token validated and stored                        |
| 400         | Bad Request           | Missing `githubToken` or token rejected by GitHub |
| 401         | Unauthorized          | Invalid or missing API key                        |
| 403         | Forbidden             | Pro subscription required                         |
| 500         | Internal Server Error | Failed to validate or store token                 |