# TeamService

**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.TeamService: 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. -->

## AddMember

`POST /spin.v1.TeamService/AddMember`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `email` | string |  |
| `role` | [TeamRole](https://spin-stack.github.io/website/reference/api/types.md#teamrole) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `member` | [TeamMember](https://spin-stack.github.io/website/reference/api/types.md#teammember) |  |

## CreateIdentityProvider

`POST /spin.v1.TeamService/CreateIdentityProvider`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string | Optional: team-specific IdP (empty = system-wide) |
| `name` | string |  |
| `providerType` | string | oidc, github, google, azure-ad |
| `issuerUrl` | string | For OIDC discovery |
| `clientId` | string |  |
| `clientSecret` | string |  |
| `scopes` | list of string |  |
| `autoJoinCelExpression` | string | Optional: auto-add users matching this |
| `roleCelExpression` | string | Optional: determine role from claims |

**Response**

| Field | Type | What it is |
|---|---|---|
| `provider` | [TeamIdentityProvider](https://spin-stack.github.io/website/reference/api/types.md#teamidentityprovider) |  |

## CreateProject

`POST /spin.v1.TeamService/CreateProject`

A team's projects: a repository and the shape of the workspace that opens it (CreateWorkspaceRequest.project_id). Made, changed and deleted by the team's admins, listed and opened by its members. A project with a workspace open on it is not deleted.

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `name` | string |  |
| `slug` | string | Made from the name when empty |
| `description` | string |  |
| `repository` | string |  |
| `ref` | string |  |
| `image` | string |  |
| `preset` | string |  |
| `networkTags` | list of string |  |
| `prebuildRefs` | list of string |  |
| `prebuildRebaseEvery` | integer (int32) | Zero is the installation's default |

**Response**

| Field | Type | What it is |
|---|---|---|
| `project` | [Project](https://spin-stack.github.io/website/reference/api/types.md#project) |  |

## CreateTeam

`POST /spin.v1.TeamService/CreateTeam`

Create a new team (can be nested under parent_id)

**Request**

| Field | Type | What it is |
|---|---|---|
| `parentId` | string | Optional: parent team ID (empty = root team) |
| `name` | string |  |
| `slug` | string | Optional, generated from name if empty |
| `description` | string |  |
| `displayName` | string | Optional: human-friendly name |

**Response**

| Field | Type | What it is |
|---|---|---|
| `team` | [Team](https://spin-stack.github.io/website/reference/api/types.md#team) |  |

## DeleteForge

`POST /spin.v1.TeamService/DeleteForge`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `forge` | string |  |

**Response**

No fields: `{}`.

## DeleteIdentityProvider

`POST /spin.v1.TeamService/DeleteIdentityProvider`

**Request**

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

**Response**

No fields: `{}`.

## DeleteNetworkPolicy

`POST /spin.v1.TeamService/DeleteNetworkPolicy`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `name` | string |  |

**Response**

No fields: `{}`.

## DeleteProject

`POST /spin.v1.TeamService/DeleteProject`

**Request**

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

**Response**

No fields: `{}`.

## DeleteSecret

`POST /spin.v1.TeamService/DeleteSecret`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `name` | string |  |

**Response**

No fields: `{}`.

## DeleteTeam

`POST /spin.v1.TeamService/DeleteTeam`

Delete team (owner only, must have no children)

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `recursive` | boolean | If true, delete children too (dangerous!) |

**Response**

No fields: `{}`.

## GetTeam

`POST /spin.v1.TeamService/GetTeam`

Get team by ID or path

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string | ID, path (e.g., "/engineering/backend") or "me": the caller's personal team |

**Response**

| Field | Type | What it is |
|---|---|---|
| `team` | [Team](https://spin-stack.github.io/website/reference/api/types.md#team) |  |
| `currentUserRole` | [TeamRole](https://spin-stack.github.io/website/reference/api/types.md#teamrole) | Role of the requesting user in this team |

## ListForges

`POST /spin.v1.TeamService/ListForges`

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `forges` | list of [TeamForge](https://spin-stack.github.io/website/reference/api/types.md#teamforge) |  |

## ListIdentityProviders

`POST /spin.v1.TeamService/ListIdentityProviders`

Identity provider management (admin only)

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string | Empty = system-wide providers |
| `page` | [PageRequest](https://spin-stack.github.io/website/reference/api/types.md#pagerequest) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `providers` | list of [TeamIdentityProvider](https://spin-stack.github.io/website/reference/api/types.md#teamidentityprovider) |  |
| `page` | [PageResponse](https://spin-stack.github.io/website/reference/api/types.md#pageresponse) |  |

## ListMembers

`POST /spin.v1.TeamService/ListMembers`

Member management

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `page` | [PageRequest](https://spin-stack.github.io/website/reference/api/types.md#pagerequest) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `members` | list of [TeamMember](https://spin-stack.github.io/website/reference/api/types.md#teammember) |  |
| `page` | [PageResponse](https://spin-stack.github.io/website/reference/api/types.md#pageresponse) |  |

## ListPrebuilds

`POST /spin.v1.TeamService/ListPrebuilds`

A project's prebuilds, to its team's members; and a build of one of its refs now, by its admins, rather than at the next look.

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `prebuilds` | list of [Prebuild](https://spin-stack.github.io/website/reference/api/types.md#prebuild) | Newest first. |

## ListProjects

`POST /spin.v1.TeamService/ListProjects`

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `projects` | list of [Project](https://spin-stack.github.io/website/reference/api/types.md#project) |  |

## ListSecrets

`POST /spin.v1.TeamService/ListSecrets`

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `secrets` | list of [TeamSecret](https://spin-stack.github.io/website/reference/api/types.md#teamsecret) |  |

## ListTeams

`POST /spin.v1.TeamService/ListTeams`

List teams (optionally filtered by parent)

**Request**

| Field | Type | What it is |
|---|---|---|
| `parentId` | string | Optional: filter by parent (empty = root teams only) |
| `includeAllDescendants` | boolean | If true, include all nested teams |
| `page` | [PageRequest](https://spin-stack.github.io/website/reference/api/types.md#pagerequest) |  |
| `everyTeam` | boolean | every_team lists the whole installation rather than the caller's own teams - the administration view, and only an instance admin may ask for it. It is asked for rather than inferred from who is calling: an admin's own Teams page should be their teams, not a list of everybody's personal team that they cannot get out of. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `teams` | list of [Team](https://spin-stack.github.io/website/reference/api/types.md#team) |  |
| `page` | [PageResponse](https://spin-stack.github.io/website/reference/api/types.md#pageresponse) |  |

## RemoveMember

`POST /spin.v1.TeamService/RemoveMember`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `userId` | string |  |

**Response**

No fields: `{}`.

## RunPrebuild

`POST /spin.v1.TeamService/RunPrebuild`

**Request**

| Field | Type | What it is |
|---|---|---|
| `projectId` | string |  |
| `ref` | string | One of the project's prebuild refs. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `prebuild` | [Prebuild](https://spin-stack.github.io/website/reference/api/types.md#prebuild) | The build, or the one already running at that commit. |

## SetForge

`POST /spin.v1.TeamService/SetForge`

A team's forges: the app it installed on its organization, from which the control plane mints the credential a brokered rule injecting that forge has the egress proxy set - an hour's, so a workspace of the team clones and pushes its private repositories with nothing of it on the disk. Set and deleted by the team's admins, after the forge has minted one with what was given; listed to its members. The app's key is never answered with again.

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `forge` | string | netpolicy.Forges: "github". |
| `appId` | string (int64) | The GitHub App's id, and its installation on the organization the team's repositories are in. |
| `installationId` | string (int64) |  |
| `privateKey` | string | The app's private key, PEM: what signs the request for an installation token. Replaces what the team held. |
| `apiUrl` | string | Where the forge's API is, https; empty is github.com's. A GitHub Enterprise Server's is https://&lt;host>/api/v3. |
| `hosts` | list of string | The exact names the credential may be sent to, 1 to 16; empty is github.com and api.github.com. A brokered rule that injects the forge and names any other host is refused it. |

**Response**

No fields: `{}`.

## SetNetworkPolicy

`POST /spin.v1.TeamService/SetNetworkPolicy`

A team's egress policies: named, and only allowing - no rule brokers - for the workspaces of the team and the teams below it. Set and deleted by its admins where the installation lets teams declare them (team_network_policies); listed by WorkspaceService.ListNetworkPolicies.

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `name` | string |  |
| `rules` | list of [NetworkRule](https://spin-stack.github.io/website/reference/api/types.md#networkrule) |  |

**Response**

No fields: `{}`.

## SetSecret

`POST /spin.v1.TeamService/SetSecret`

A team's secrets: what a brokered network rule has the host's egress proxy add to a request, so a workspace of the team uses a key it never holds. Set and deleted by the team's admins, listed by name to its members; a value is never answered with again.

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `name` | string | Lower-case letters, digits and dashes, starting with a letter; what a rule names it by. |
| `value` | string | At most 8 KiB of visible ASCII. Replaces what the name held. |
| `hosts` | list of string | The exact names the secret may be sent to, 1 to 16: a brokered rule that injects it and names any other host is refused it. |
| `ref` | string | In place of value: the ARN of a Secrets Manager secret or a Parameter Store parameter the team keeps it in, read as the team (InstallationSettings.team_secrets_role) now and whenever a host asks for it. |

**Response**

No fields: `{}`.

## UpdateIdentityProvider

`POST /spin.v1.TeamService/UpdateIdentityProvider`

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `autoJoinCelExpression` | string |  |
| `roleCelExpression` | string |  |
| `enabled` | boolean |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `provider` | [TeamIdentityProvider](https://spin-stack.github.io/website/reference/api/types.md#teamidentityprovider) |  |

## UpdateMemberRole

`POST /spin.v1.TeamService/UpdateMemberRole`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `userId` | string |  |
| `role` | [TeamRole](https://spin-stack.github.io/website/reference/api/types.md#teamrole) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `member` | [TeamMember](https://spin-stack.github.io/website/reference/api/types.md#teammember) |  |

## UpdateProject

`POST /spin.v1.TeamService/UpdateProject`

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `slug` | string |  |
| `description` | string |  |
| `repository` | string |  |
| `ref` | string |  |
| `image` | string |  |
| `preset` | string |  |
| `networkTags` | list of string |  |
| `prebuildRefs` | list of string |  |
| `prebuildRebaseEvery` | integer (int32) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `project` | [Project](https://spin-stack.github.io/website/reference/api/types.md#project) |  |

## UpdateTeam

`POST /spin.v1.TeamService/UpdateTeam`

Update team settings

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `description` | string |  |
| `displayName` | string | Human-friendly name |

**Response**

| Field | Type | What it is |
|---|---|---|
| `team` | [Team](https://spin-stack.github.io/website/reference/api/types.md#team) |  |