Skip to content

Teams API Reference ​

GET /teams/ ​

List teams

Use from an administrator console to list teams, ordered by ascending team ID. See REST pagination for the shared collection contract.

Required permission — iam:teams:any (or iam:teams:team scoped to the target team)

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "created_at": "2026-01-01T00:00:00Z",
      "id": "01J8Z3TEAM000000000000001",
      "name": "Acme",
      "slug": "acme",
      "status": "active"
    }
  ],
  "next_cursor": ""
}

Errors ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
500authentication service unavailableInternal Server Error

POST /teams/ ​

Create a team

Use when provisioning a new tenant or workspace. Slug and name are required; status defaults to active.

Required permission — iam:teams:any (or iam:teams:team scoped to the target team)

Request body (application/json) ​

FieldTypeRequired
namestringYes
slugstringYes
statusstringNo
json
{
  "name": "Acme",
  "slug": "acme",
  "status": "active"
}

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "01J8Z3TEAM000000000000001",
  "name": "Acme",
  "slug": "acme",
  "status": "active"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
409the resource already existsConflict
500authentication service unavailableInternal Server Error

DELETE /teams/{id} ​

Delete a team

Use to remove a team and its dependent administrative records. The operation invalidates affected permission versions and is audited.

Required permission — iam:teams:any (or iam:teams:team scoped to the target team)

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /teams/{id} ​

Get a team

Use to retrieve one team by ULID for an administrative view or downstream provisioning step.

Required permission — iam:teams:any (or iam:teams:team scoped to the target team)

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "01J8Z3TEAM000000000000001",
  "name": "Acme",
  "slug": "acme",
  "status": "active"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

PATCH /teams/{id} ​

Update a team

Use to rename or change a team's slug/status. At least one field is required; status must be active or disabled. Disabling a team suppresses its scoped grants and invalidates permission versions for affected members; independent platform grants remain available.

Required permission — iam:teams:any (or iam:teams:team scoped to the target team)

Path parameters ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
namestringNo
slugstringNo
statusstringNo
json
{
  "name": "Acme Europe",
  "status": "active"
}

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "01J8Z3TEAM000000000000001",
  "name": "Acme Europe",
  "slug": "acme",
  "status": "active"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error