# ForgeService

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://docs.spinbox.dev/reference/status.md); what Spinbox does not do is on [Limitations](https://docs.spinbox.dev/overview/limitations.md).

> spin.v1.ForgeService: each procedure, its request and its response.

<!-- Generated by tools/refgen from spin:internal/controlplane/apidocs/spin.v1.openapi.json. Edit the source, not this file. -->

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

`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](https://docs.spinbox.dev/reference/api/types.md#forgeapp) |  |

## 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](https://docs.spinbox.dev/reference/api/types.md#forgeconnection) |  |

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

`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

`POST /spin.v1.ForgeService/ListConnections`

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `connections` | list of [ForgeConnection](https://docs.spinbox.dev/reference/api/types.md#forgeconnection) |  |

## 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](https://docs.spinbox.dev/reference/api/types.md#forgeapp) |  |

## PollDeviceConnect

`POST /spin.v1.ForgeService/PollDeviceConnect`

**Request**

| Field | Type | What it is |
|---|---|---|
| `handle` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `connection` | [ForgeConnection](https://docs.spinbox.dev/reference/api/types.md#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

`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](https://docs.spinbox.dev/reference/api/types.md#forgerepository) |  |

## 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](https://docs.spinbox.dev/reference/api/types.md#forgeapp) |  |

## 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://&lt;host>/api/v3, and its web origin https://&lt;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

`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

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