Skip to main content
POST
Repositories

Overview

Connections are in limited preview and apply to goals on the agent loop.
Keys and sign-ins. A key is accepted only for a system that authorizes with one. Keys and client secrets you enter are stored encrypted, used only for that connection, and deleted when you revoke it.

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. NetSuite and Coupa require client. Zoho Books requires region, the ending of your Zoho address (com, eu, in, com.au, jp, ca, sa, com.cn), since a sign-in is valid only there. Other systems refuse both:
Reconnect reuses the stored client and region, or new ones sent. A Zoho Books connection without a recorded region answers 400 region_required until one is sent. 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 (and api_secret, where paired) is stored encrypted and connects the account at once: active, link null, credential: "stored". A refused key: 400 key_refused, nothing stored; api_key elsewhere: 400 invalid_request.

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 send api_key (and api_secret), returning active, no link.
Status checks run on list or read, at most every 10 minutes: an ended sign-in shows expired, a disconnected account revoked. GitHub uninstall also revokes access.

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.