Menu
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

NameType
org_iduuid

Query parameters

NameDefault
include_membersnone

Body keys (JSON)

KeyRequiredDefault
coloroptional or conditionalnone
descriptionoptional or conditionalnone
nameoptional or conditionalnone

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

StatusCode
400Team name is required message
403Manager+ role required to create teams message
403Not a member of this organization message
404Organization 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

NameType
org_iduuid
team_iduuid

Body keys (JSON)

KeyRequiredDefault
coloroptional or conditionalnone
descriptionoptional or conditionalnone
nameoptional or conditionalnone

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

StatusCode
400Team name cannot be empty message
403Manager+ role required to delete teams message
403Permission denied message
404Organization not found message
404Team 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

NameType
org_iduuid
team_iduuid

Body keys (JSON)

KeyRequiredDefault
user_idsoptional 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

StatusCode
400user_ids is required message
403Not a member of this organization message
403Permission denied message
404Organization not found message
404Team 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

NameType
org_iduuid
team_iduuid
user_idint

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

StatusCode
403Permission denied message
404Organization not found message
404Team not found message
404User 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

NameDefault
organization_idnone

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

StatusCode
400organization_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)

All Auth resources
Start Free Explore our Products