GETPOST
organizations/{org_id}/teams/
User API
GET /api/organizations/<org_id>/teams/ : list org teams POST /api/organizations/<org_id>/teams/ : create team (manager+)
URL
- User APIhttps://auth.mattering.io/api/organizations/{org_id}/teams/
Path parameters
Query parameters
| Name | Default |
include_members | none |
Body keys (JSON)
| Key | Required | Default |
color | optional or conditional | none |
description | optional or conditional | none |
name | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"teams": [
{
"id": "...",
"name": "...",
"description": "...",
"color": "...",
"member_count": "...",
"created_at": "2026-01-01T00:00:00Z",
"members": [
{
"id": "...",
"email": "...",
"first_name": "...",
"last_name": "...",
"is_lead": true,
"joined_at": "2026-01-01T00:00:00Z"
}
]
}
]
}
201 bare JSON object (no envelope)
{
"team": {
"id": "...",
"name": "...",
"description": "...",
"color": "...",
"member_count": "...",
"created_at": "2026-01-01T00:00:00Z",
"members": [
{
"id": "...",
"email": "...",
"first_name": "...",
"last_name": "...",
"is_lead": true,
"joined_at": "2026-01-01T00:00:00Z"
}
]
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | Team name is required message |
| 403 | Manager+ role required to create teams message |
| 403 | Not a member of this organization message |
| 404 | Organization not found message |
Example
curl -X POST "https://auth.mattering.io/api/organizations/ORG_ID/teams/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"color": "...",
"description": "...",
"name": "..."
}'
Source: mattering_auth/team_views.py (team_views.TeamListCreateView)
PATCHDELETE
organizations/{org_id}/teams/{team_id}/
User API
PATCH /api/organizations/<org_id>/teams/<team_id>/ : update team DELETE /api/organizations/<org_id>/teams/<team_id>/ : delete team (manager+)
URL
- User APIhttps://auth.mattering.io/api/organizations/{org_id}/teams/{team_id}/
Path parameters
| Name | Type |
org_id | uuid |
team_id | uuid |
Body keys (JSON)
| Key | Required | Default |
color | optional or conditional | none |
description | optional or conditional | none |
name | optional or conditional | none |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"success": true,
"message": "..."
}
200 bare JSON object (no envelope)
{
"team": {
"id": "...",
"name": "...",
"description": "...",
"color": "...",
"member_count": "...",
"created_at": "2026-01-01T00:00:00Z",
"members": [
{
"id": "...",
"email": "...",
"first_name": "...",
"last_name": "...",
"is_lead": true,
"joined_at": "2026-01-01T00:00:00Z"
}
]
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | Team name cannot be empty message |
| 403 | Manager+ role required to delete teams message |
| 403 | Permission denied message |
| 404 | Organization not found message |
| 404 | Team not found message |
Example
curl -X PATCH "https://auth.mattering.io/api/organizations/ORG_ID/teams/TEAM_ID/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"color": "...",
"description": "...",
"name": "..."
}'
Source: mattering_auth/team_views.py (team_views.TeamDetailView)
GETPOST
organizations/{org_id}/teams/{team_id}/members/
User API
GET /api/organizations/<org_id>/teams/<team_id>/members/ : list members POST /api/organizations/<org_id>/teams/<team_id>/members/ : add member(s)
URL
- User APIhttps://auth.mattering.io/api/organizations/{org_id}/teams/{team_id}/members/
Path parameters
| Name | Type |
org_id | uuid |
team_id | uuid |
Body keys (JSON)
| Key | Required | Default |
user_ids | optional or conditional | [] |
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 bare JSON object (no envelope)
{
"added": [
"..."
],
"skipped": [
"..."
],
"team": {
"id": "...",
"name": "...",
"description": "...",
"color": "...",
"member_count": "...",
"created_at": "2026-01-01T00:00:00Z",
"members": [
{
"id": "...",
"email": "...",
"first_name": "...",
"last_name": "...",
"is_lead": true,
"joined_at": "2026-01-01T00:00:00Z"
}
]
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | user_ids is required message |
| 403 | Not a member of this organization message |
| 403 | Permission denied message |
| 404 | Organization not found message |
| 404 | Team not found message |
Example
curl -X POST "https://auth.mattering.io/api/organizations/ORG_ID/teams/TEAM_ID/members/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"user_ids": []
}'
Source: mattering_auth/team_views.py (team_views.TeamMemberListView)
DELETE
organizations/{org_id}/teams/{team_id}/members/{user_id}/
User API
DELETE /api/organizations/<org_id>/teams/<team_id>/members/<user_id>/
URL
- User APIhttps://auth.mattering.io/api/organizations/{org_id}/teams/{team_id}/members/{user_id}/
Path parameters
| Name | Type |
org_id | uuid |
team_id | uuid |
user_id | int |
Responses
200 bare JSON object (no envelope)
{
"success": true,
"team": {
"id": "...",
"name": "...",
"description": "...",
"color": "...",
"member_count": "...",
"created_at": "2026-01-01T00:00:00Z",
"members": [
{
"id": "...",
"email": "...",
"first_name": "...",
"last_name": "...",
"is_lead": true,
"joined_at": "2026-01-01T00:00:00Z"
}
]
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 403 | Permission denied message |
| 404 | Organization not found message |
| 404 | Team not found message |
| 404 | User is not a member of this team message |
Example
curl -X DELETE "https://auth.mattering.io/api/organizations/ORG_ID/teams/TEAM_ID/members/USER_ID/" \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"
Source: mattering_auth/team_views.py (team_views.TeamMemberRemoveView)
GET
user/teams/
User API
GET /api/user/teams/?organization_id=... Returns the current user's teams (with IDs) for a given organization. Used by apps to resolve team-based resource access.
URL
- User APIhttps://auth.mattering.io/api/user/teams/
Query parameters
| Name | Default |
organization_id | none |
Responses
200 bare JSON object (no envelope)
{
"teams": [
{
"id": "...",
"name": "...",
"color": "...",
"is_lead": true
}
],
"team_ids": [
"..."
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
| 400 | organization_id is required message |
Example
curl -X GET "https://auth.mattering.io/api/user/teams/?organization_id=..." \
-H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"
Source: mattering_auth/team_views.py (team_views.UserTeamsView)