# SetupService

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

> spin.v1.SetupService: 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. -->

SetupService handles initial platform setup and admin bootstrap. Most endpoints require admin authentication, except GetSetupStatus and PasswordLogin.

## ChangePassword

`POST /spin.v1.SetupService/ChangePassword`

Change admin password (requires auth) Called after initial login when force_password_change is true

**Request**

| Field | Type | What it is |
|---|---|---|
| `currentPassword` | string |  |
| `newPassword` | string |  |

**Response**

No fields: `{}`.

## CompleteSetup

`POST /spin.v1.SetupService/CompleteSetup`

Mark setup wizard as complete (requires admin)

**Request**

No fields: `{}`.

**Response**

No fields: `{}`.

## ConfigureGitHubOAuth

`POST /spin.v1.SetupService/ConfigureGitHubOAuth`

Configure GitHub OAuth credentials (requires admin) Encrypts and stores client_secret in the database

**Request**

| Field | Type | What it is |
|---|---|---|
| `clientId` | string |  |
| `clientSecret` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `callbackUrl` | string | The callback URL to configure in GitHub OAuth app settings |

## DisableBootstrapAdmin

`POST /spin.v1.SetupService/DisableBootstrapAdmin`

Disable the bootstrap admin account (requires admin + OAuth must be configured) This removes password login capability for the bootstrap user

**Request**

No fields: `{}`.

**Response**

No fields: `{}`.

## EnableDevMode

`POST /spin.v1.SetupService/EnableDevMode`

Enable dev mode (requires admin) Creates a "dev" identity provider that allows login without real OAuth Only use for local development - not for production

**Request**

No fields: `{}`.

**Response**

No fields: `{}`.

## GetSetupStatus

`POST /spin.v1.SetupService/GetSetupStatus`

Get current setup status (public - no auth required) Returns whether setup wizard needs to be completed

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `needsSetup` | boolean | True until the setup wizard has been completed: where the dashboard sends everybody. |
| `hasOauth` | boolean | True if any OAuth/OIDC provider is configured |
| `setupCompleted` | boolean | True if setup wizard has been completed |
| `forcePasswordChange` | boolean | True if current admin must change their password |
| `baseDomain` | string | The configured base domain (if any) |
| `hasBootstrapAdmin` | boolean | True if bootstrap admin is still active (should be disabled after OAuth setup) |
| `registrationMode` | [RegistrationMode](https://spin-stack.github.io/website/reference/api/types.md#registrationmode) | Current registration mode (open, whitelist, closed) |
| `hasStorage` | boolean | True if the object store is configured; until it is, no workspace can be created |
| `signedIn` | boolean | True if whoever asked is signed in: the wizard starts at the sign-in until they are, whatever the installation already has. |
| `development` | boolean | True for a development installation, where the mock identity provider may be enabled. |

## PasswordLogin

`POST /spin.v1.SetupService/PasswordLogin`

Login with email/password (public - for admin bootstrap) Only works for users with admin_credentials

**Request**

| Field | Type | What it is |
|---|---|---|
| `email` | string |  |
| `password` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `user` | [User](https://spin-stack.github.io/website/reference/api/types.md#user) |  |
| `sessionToken` | string |  |
| `expiresAt` | `Timestamp` |  |
| `forcePasswordChange` | boolean | True if user must change password before proceeding |