Docs

Delete team

DELETE
/teams/{team_id}

Deactivates the team.

The team is tombstoned rather than erased: it stays readable through getTeam with status deactivated. Its memberships are removed and the users whose lifecycle it owns are deactivated with it.

The request is idempotent. Deleting a team that is already deactivated or doesn't exist succeeds without changing anything.

A team that still owns a project is refused with 409 team.owns_project: deactivating it would leave the project owned by a dead team and so unmanageable. No endpoint releases that ownership yet, so such a team cannot currently be deactivated through the API.

Authorization

oauth2 team.delete
headerAuthorizationBearer <token>

Scope: team.delete

Path Parameters

team_id*string

The unique identifier of the team.

Match^[a-zA-Z0-9_-]+$

Response Body

The team is deactivated.

Example Request
import { createZitadelClient } from "@zitadel/api/client";const client = createZitadelClient({  baseUrl: process.env.ZITADEL_URL ?? "http://localhost:8080",  token: process.env.ZITADEL_PROJECT_SECRET!, // server-side only});await client.deleteTeam("team_01KZZY8PX8K8ATNVDSMRCZY4N1");
Example Response
Empty

Was this helpful?