Skip to main content
POST
Repositories

Overview

Connections are in limited preview and apply to goals on the agent loop.
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).
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:
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, CRM, tax and shipping. Nothing fetched is stored. For a system that authorizes with a key, send it with the start:
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.