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

# Repositories

> 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 systems. A connection authorizes an agent to work inside a repository or a supported business system.

**Keys and sign-ins.** A key is accepted only for a system that authorizes with one (TaxJar, ShipEngine). Keys and client secrets you enter are stored encrypted, used only for that connection, and deleted when you revoke it. Sign-ins to other systems are held by the systems' authorization service, never by OneShot in readable form. Repositories and sign-in systems never take a key.

## Connect

`POST /v1/connections` with a signed **write proof** ([Authentication schemes](/api-reference/openapi#authentication-schemes)).

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

GitHub takes only `name` and `kind`. Open `link`, approve on GitHub and choose repositories: they become the scope of the `active` connection. The link works once, for an hour.

For a business system:

```json theme={null}
{ "name": "acme-books", "kind": "app", "system": "quickbooks" }
```

`system` is a catalogue id other than `github`. Unavailable: `503 not_configured`, nothing created; extra fields: `400 invalid_request`. Approve on the system's page; only an active account belonging to this connection is activated (`403 not_owner` otherwise). Connections to one system take different names.

Read-only tools require an active `connection_id`: [accounting](/api-reference/connections/accounting), [CRM](/api-reference/connections/crm), [tax](/api-reference/connections/tax) and [shipping](/api-reference/connections/shipping). Nothing fetched is stored.

For a system that authorizes with a key, send it with the start:

```json theme={null}
{ "name": "acme-tax", "kind": "app", "system": "taxjar", "api_key": "<your TaxJar key>" }
```

The key is stored encrypted and connects the account in this request: the answer is `active`, `link` null, `credential: "stored"`. A refused key: `400 key_refused`, nothing stored; `api_key` elsewhere: `400 invalid_request`. Systems: `taxjar`, `shipengine`.

## List and revoke

* `GET /v1/connections`: `status` (`pending`, `active`, `expired`, `revoked`), `system`, `account_label` (may be null), `scope.repositories`, and `credential: "stored"` when an encrypted credential exists.
* `DELETE /v1/connections/{id}`: the next use fails; the system grant is ended where possible and any stored credential deleted.
* `POST /v1/connections/{id}/reconnect`: one-hour sign-in link for `expired` connections or active CRM connections missing write permission; otherwise `409 not_expired`. Key-authorized connections may send `api_key`, returning `active` without a link.

Business-system status is checked on list or read, at most every 10 minutes: an ended sign-in shows `expired`, a disconnected account `revoked`.

Uninstalling the application on GitHub also revokes it.

## How it is used

Any session of the goal may use a connection in scope. Each use gets a one-repository token, expiring within the hour, never returned in a tool result and masked in stored steps and logs. Out-of-scope repositories, revoked connections and other owners' connections are refused.


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