ForgeService
ForgeService is a person’s account on a forge, connected through the installation’s GitHub App. (spin#758): the control plane keeps the token, lists the person’s repositories with it, and a. host’s egress proxy sets it on their workspaces’ brokered requests. No workspace holds it.
CompleteAppCreation
Section titled “CompleteAppCreation”POST /spin.v1.ForgeService/CompleteAppCreation
Request
| Field | Type | What it is |
|---|---|---|
code | string | |
state | string | |
binding | string |
Response
| Field | Type | What it is |
|---|---|---|
app | ForgeApp |
CompleteConnect
Section titled “CompleteConnect”POST /spin.v1.ForgeService/CompleteConnect
Request
| Field | Type | What it is |
|---|---|---|
code | string | |
state | string | |
binding | string |
Response
| Field | Type | What it is |
|---|---|---|
connection | ForgeConnection |
DeleteForgeApp
Section titled “DeleteForgeApp”POST /spin.v1.ForgeService/DeleteForgeApp
Takes the app out of use at once. Every connection through it is revoked at the forge, and the app is gone when that is done.
Request
| Field | Type | What it is |
|---|---|---|
forge | string |
Response
No fields: {}.
Disconnect
Section titled “Disconnect”POST /spin.v1.ForgeService/Disconnect
Forgets the token and revokes it at the forge.
Request
| Field | Type | What it is |
|---|---|---|
forge | string |
Response
No fields: {}.
ListConnections
Section titled “ListConnections”POST /spin.v1.ForgeService/ListConnections
Request
No fields: {}.
Response
| Field | Type | What it is |
|---|---|---|
connections | list of ForgeConnection |
ListForgeApps
Section titled “ListForgeApps”POST /spin.v1.ForgeService/ListForgeApps
The installation’s app on each forge: whether a person can connect, and where. Its secrets are never answered with.
Request
No fields: {}.
Response
| Field | Type | What it is |
|---|---|---|
apps | list of ForgeApp |
PollDeviceConnect
Section titled “PollDeviceConnect”POST /spin.v1.ForgeService/PollDeviceConnect
Request
| Field | Type | What it is |
|---|---|---|
handle | string |
Response
| Field | Type | What it is |
|---|---|---|
connection | ForgeConnection | Set once the person approved: the connection, kept. Unset is pending: poll again after interval_seconds, which the forge may have lengthened. |
intervalSeconds | integer (int32) |
SearchRepositories
Section titled “SearchRepositories”POST /spin.v1.ForgeService/SearchRepositories
The repositories the person’s account reaches that match query, as the forge searches them with the person’s token: what they can see there is what they can pick here.
Request
| Field | Type | What it is |
|---|---|---|
forge | string | |
query | string | Empty lists the account’s repositories, most recently pushed first. |
Response
| Field | Type | What it is |
|---|---|---|
repositories | list of ForgeRepository |
SetForgeApp
Section titled “SetForgeApp”POST /spin.v1.ForgeService/SetForgeApp
Keeping an app that was made elsewhere. Refused while the forge has one: an app is never edited, because another client id could not revoke what this one granted.
Request
| Field | Type | What it is |
|---|---|---|
forge | string | |
appId | string (int64) | |
slug | string | |
clientId | string | |
clientSecret | string | |
webhookSecret | string | |
apiUrl | string | As StartAppCreationRequest’s. |
webUrl | string |
Response
| Field | Type | What it is |
|---|---|---|
app | ForgeApp |
StartAppCreation
Section titled “StartAppCreation”POST /spin.v1.ForgeService/StartAppCreation
Making the app, by an instance admin, through the forge’s manifest flow: StartAppCreation answers the form the browser posts to the forge, which makes the app and sends the admin back with a code; CompleteAppCreation exchanges it for the app’s credentials. Nobody copies a key.
Request
| Field | Type | What it is |
|---|---|---|
forge | string | |
organization | string | The organization the app belongs to; empty is the admin’s own account. |
apiUrl | string | Empty is github.com’s; a GitHub Enterprise Server’s API is https://<host>/api/v3, and its web origin https://<host>. |
webUrl | string | |
public | boolean | Whether any account can install it. A private app installs only on the account that owns it, so only that account’s repositories are reached. |
Response
| Field | Type | What it is |
|---|---|---|
formUrl | string | Where to send the browser: a page of this control plane’s that posts the manifest to the forge, because the dashboard’s own policy lets it post nowhere else. |
state | string | |
binding | string | A secret for the client that began this, kept where only it reads it and never in a URL: CompleteAppCreation requires it with the state. |
StartConnect
Section titled “StartConnect”POST /spin.v1.ForgeService/StartConnect
Connecting: StartConnect answers where the person authorizes the app and a binding only this client keeps; the forge sends the browser back to redirect_uri with a code and the state, and CompleteConnect exchanges them, with the binding, for the person’s token.
Request
| Field | Type | What it is |
|---|---|---|
forge | string | |
redirectUri | string | The dashboard’s /git/callback, over https; anything else is refused. Empty is the installation’s own. |
Response
| Field | Type | What it is |
|---|---|---|
authorizeUrl | string | |
state | string | |
binding | string | A secret for the client that began this, kept where only it reads it and never in a URL: CompleteConnect requires it with the state. |
StartDeviceConnect
Section titled “StartDeviceConnect”POST /spin.v1.ForgeService/StartDeviceConnect
Connecting from somewhere with no browser to send back to, the CLI: the control plane asks the forge for a device code (RFC 8628) and keeps it, and answers with the code the person types on the forge’s page and a handle only the caller can poll with. PollDeviceConnect asks the forge, at most once an interval, and on the person’s approval keeps their token as CompleteConnect does: once, for the person who began it.
Request
| Field | Type | What it is |
|---|---|---|
forge | string |
Response
| Field | Type | What it is |
|---|---|---|
handle | string | What PollDeviceConnect is asked with: a secret of the caller’s, polled by them alone. The forge’s device code stays on the control plane. |
userCode | string | What the person types at verification_uri, signed in to the forge. |
verificationUri | string | |
expiresAt | Timestamp | |
intervalSeconds | integer (int32) | How long to wait before each poll. |
Generated by task reference from spin/internal/controlplane/apidocs/spin.v1.openapi.json at 51f7e0dea.
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

