Appearance
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
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 500 | authentication service unavailable | Internal 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)
| Field | Type | Required |
|---|---|---|
| name | string | Yes |
| slug | string | Yes |
| status | string | No |
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
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 409 | the resource already exists | Conflict |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"id": "01J8Z3TEAM000000000000001",
"name": "Acme",
"slug": "acme",
"status": "active"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| name | string | No |
| slug | string | No |
| status | string | No |
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
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal Server Error |