Connections
Manage external provider connections (GitHub, GitLab) for repository sync.
Overview
Connections store encrypted access tokens for GitHub and GitLab. They are used by sync configurations to import from or export to external repositories.
Tokens are validated against the provider API on creation and encrypted with AES-256-GCM before storage. Plaintext tokens are never stored or returned after creation.
Create Connection
POST /v1/connectionsPermission: Master API key only.
{
"provider": "github",
"label": "My GitHub PAT",
"access_token": "ghp_xxxxxxxxxxxx"
}Fields
| Field | Required | Description |
|---|---|---|
provider | Yes | "github" or "gitlab" |
label | Yes | Human-readable name for this connection |
access_token | Yes | Personal access token or bearer token |
Response 201
{
"id": "abc123",
"provider": "github",
"label": "My GitHub PAT",
"external_username": "octocat",
"created_at": "2026-04-05T12:00:00Z"
}The external_username is automatically fetched from the provider API during token validation.
List Connections
GET /v1/connectionsPermission: Any API key (master or scoped).
Response 200
{
"connections": [
{
"id": "abc123",
"provider": "github",
"label": "My GitHub PAT",
"external_username": "octocat",
"last_synced_at": "2026-04-05T12:30:00Z",
"created_at": "2026-04-05T12:00:00Z",
"updated_at": "2026-04-05T12:00:00Z"
}
]
}Access tokens are never included in responses.
Update Connection
PATCH /v1/connections/:idPermission: Master API key only.
{
"label": "Updated label",
"access_token": "ghp_new_token"
}Both fields are optional. If access_token is provided, it is re-validated against the provider API and the external_username is updated.
Response 200
{ "updated": true }Test Connection
POST /v1/connections/:id/testPermission: Any API key (master or scoped).
Validates the stored token against the provider API without modifying anything.
Response 200
{
"valid": true,
"username": "octocat"
}If the token is expired or revoked:
{
"valid": false,
"error": "GitHub token validation failed: 401 Bad credentials"
}Delete Connection
DELETE /v1/connections/:idPermission: Master API key only.
Deleting a connection cascades to all sync configurations that reference it.
Response 200
{ "deleted": true }SDK Examples
// Create a GitHub connection
const { data: conn } = await git.connections.create({
provider: "github",
label: "CI/CD Token",
access_token: "ghp_xxxxxxxxxxxx",
});
console.log(conn.external_username); // "octocat"
// List all connections
const { data } = await git.connections.list();
console.log(data.connections);
// Rotate a token
await git.connections.update(conn.id, {
access_token: "ghp_new_token",
});
// Test connection health
const { data: test } = await git.connections.test(conn.id);
console.log(test.valid); // true
// Delete
await git.connections.delete(conn.id);