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

# Connections

> Let an agent work inside your repositories on a limited token you can revoke

## Overview

<Note>Connections are in limited preview and apply to goals on the agent loop.</Note>

By default OneShot holds no access to your system: you send cases in and take results back. A connection is for work an agent must do inside a repository. You approve on GitHub's own page and pick the repositories. OneShot never sees your password or a long-lived key, and takes none: no route accepts a pasted key, password or token.

## Connect

`POST /v1/connections` with a signed **write proof**.

```json theme={null}
{ "name": "acme-github", "kind": "github" }
```

Only `name` and `kind` are accepted; any other field is refused. The answer holds a `link`. Open it, approve the application on GitHub and choose the repositories. GitHub sends you back to OneShot, which marks the connection `active` with the repositories you chose as its scope. The link works once and expires in an hour.

## List and revoke

* `GET /v1/connections`: your connections with `status` (`pending`, `active`, `revoked`) and `scope.repositories`.
* `DELETE /v1/connections/{id}`: revokes it. The next use fails, and the grant is ended on GitHub.

You can also uninstall the application on GitHub at any time; the next use then finds the connection revoked.

## How it is used

Any session of the goal may use a connection, inside its scope. Each use gets a token for one repository only, which expires within the hour. A token is never returned in a tool result and is masked in stored steps and logs. A repository outside the scope, a revoked connection, and a connection of another owner are each refused.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.