# TeamService

**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.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://docs.spinbox.dev/reference/api/types.md#teamrole) |  |

**Response**

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

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

## 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: `{}`.

## 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://docs.spinbox.dev/reference/api/types.md#team) |  |
| `currentUserRole` | [TeamRole](https://docs.spinbox.dev/reference/api/types.md#teamrole) | Role of the requesting user in this team |

## GetTeamCosts

`POST /spin.v1.TeamService/GetTeamCosts`

What the team's workspaces cost in the month in progress, each and summed, for the team's admins: a member reads their own workspace's (WorkspaceService.GetWorkspaceCost) and nobody else's. A workspace is the team's whose it was on the last day it cost anything; a team below this one is not counted in it.

**Request**

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `month` | `Timestamp` | The month in progress: its first instant, UTC. |
| `readAt` | `Timestamp` | When the bill was last read; unset where it never was - an installation with no bill scope - and then nothing below is known and nothing is to be drawn. |
| `currency` | string | ISO 4217; every amount here is in millionths of it. |
| `total` | [CostShare](https://docs.spinbox.dev/reference/api/types.md#costshare) | Its workspaces, summed. |
| `workspaces` | list of [TeamWorkspaceCost](https://docs.spinbox.dev/reference/api/types.md#teamworkspacecost) | Costliest first. |

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

**Response**

| Field | Type | What it is |
|---|---|---|
| `providers` | list of [TeamIdentityProvider](https://docs.spinbox.dev/reference/api/types.md#teamidentityprovider) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |

## ListMembers

`POST /spin.v1.TeamService/ListMembers`

Member management

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `page` | [PageRequest](https://docs.spinbox.dev/reference/api/types.md#pagerequest) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `members` | list of [TeamMember](https://docs.spinbox.dev/reference/api/types.md#teammember) |  |
| `page` | [PageResponse](https://docs.spinbox.dev/reference/api/types.md#pageresponse) |  |

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

## RemoveMember

`POST /spin.v1.TeamService/RemoveMember`

**Request**

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

**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://docs.spinbox.dev/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 (the setting 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://docs.spinbox.dev/reference/api/types.md#teamidentityprovider) |  |

## UpdateMemberRole

`POST /spin.v1.TeamService/UpdateMemberRole`

**Request**

| Field | Type | What it is |
|---|---|---|
| `teamId` | string |  |
| `userId` | string |  |
| `role` | [TeamRole](https://docs.spinbox.dev/reference/api/types.md#teamrole) |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `member` | [TeamMember](https://docs.spinbox.dev/reference/api/types.md#teammember) |  |

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