Menu
GETPOST workspaces/ User API

GET /api/workspaces/?organization_id=<uuid> returns list visible workspaces. POST /api/workspaces/ body: {organization_id, name, color?, description?}

URL

  • User APIhttps://auth.mattering.io/api/workspaces/

Query parameters

NameDefault
organization_idnone

Body keys (JSON)

KeyRequiredDefault
coloroptional or conditionalnone
descriptionoptional or conditionalnone
nameoptional or conditionalnone
organization_idoptional 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)

[]

200 bare JSON object (no envelope)

{
  "...": "..."
}

201 bare JSON object (no envelope)

{
  "success": true,
  "workspace": {
    "...": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400Workspace name is required message
400Workspace name must be 255 characters or less message
403forbidden
404Organization not found or access denied message

Example

curl -X POST "https://auth.mattering.io/api/workspaces/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "color": "...",
  "description": "...",
  "name": "...",
  "organization_id": "..."
}'

Source: mattering_auth/workspace_views.py (workspace_views.WorkspaceListCreateView)

POST workspaces/upsert/ Service tier

POST /api/internal/workspaces/upsert/

Idempotently create-or-update a canonical workspace. Used by the reconciliation tool to seed/merge existing per-app spaces.

Body JSON:
  * organization_id (required, uuid str)
  * name (required)
  * public_id (optional) - reuse to make the call idempotent and to seed
    from an existing Productivity Space.public_id
  * seed (optional bool) - when true, this caller is authoritative for the
    public_id: if a canonical row already exists for (org, name) under a
    different public_id, it is re-keyed to the supplied public_id. Only the
    seed source (Productivity) sets this.
  * color, description, icon_letter, order (optional). On an existing
    workspace a field that is left out is left alone.
  * owner_user_id (optional int) / owner_email (optional str)
  * members (optional list of {user_id?, email?, role}) - identity by auth
    user id or email (thin-mirror apps whose local pks don't match auth)

Matching precedence (idempotent, order-independent across parallel app deploys): 1. exact public_id match 2. (organization, normalized name) match via slug 3. otherwise create a new canonical workspace

Response: 200 {created: bool, workspace: {...}}

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/upsert/

Body keys (JSON)

KeyRequiredDefault
coloroptional or conditionalnone
descriptionoptional or conditionalnone
icon_letteroptional or conditionalnone
membersoptional or conditionalnone
nameoptional or conditionalnone
orderoptional or conditionalnone
organization_idoptional or conditionalnone
owner_emailoptional or conditionalnone
owner_user_idoptional or conditionalnone
public_idoptional or conditionalnone
seedoptional 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)

{
  "created": true,
  "workspace": "..."
}

400 bare JSON object (no envelope)

...

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
400last_owner
400organization_id and name are required message
404organization_not_found

Example

curl -X POST "https://auth.mattering.io/api/internal/workspaces/upsert/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "color": "...",
  "description": "...",
  "icon_letter": "...",
  "members": "...",
  "name": "...",
  "order": "...",
  "organization_id": "...",
  "owner_email": "..."
}'

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.upsert_workspace)

GET workspaces/{public_id}/ Service tier

GET /api/internal/workspaces/<public_id>/ returns workspace detail or 404.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/

Path parameters

NameType
public_idstr

Responses

200 bare JSON object (no envelope)

...

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404workspace_not_found

Example

curl -X GET "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.get_workspace)

GETPUTDELETE workspaces/{public_id}/ User API

GET / PUT / DELETE /api/workspaces/<public_id>/.

URL

  • User APIhttps://auth.mattering.io/api/workspaces/{public_id}/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
icon_letteroptional or conditionalnone
nameoptional or conditionalnone
orderoptional 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)

{
  "...": "..."
}

200 bare JSON object (no envelope)

{
  "success": true,
  "public_id": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400Workspace name is required message
403You do not have permission to delete this workspace message
403You do not have permission to edit this workspace message
404Workspace not found message

Example

curl -X PUT "https://auth.mattering.io/api/workspaces/PUBLIC_ID/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "icon_letter": "...",
  "name": "...",
  "order": "..."
}'

Source: mattering_auth/workspace_views.py (workspace_views.WorkspaceDetailView)

POST workspaces/{public_id}/agents/remove/ Service tier

POST /api/internal/workspaces/<public_id>/agents/remove/

Deactivates an agent membership (soft delete, keeps the audit trail). Filters on member_type='agent' so a crafted agent_public_id can never deactivate a human row. Idempotent: removing an absent agent returns removed: false, not an error.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/agents/remove/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
agent_public_idoptional 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)

{
  "ok": true,
  "removed": true
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400agent_public_id_required
400invalid_json
404workspace_not_found

Example

curl -X POST "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/agents/remove/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_public_id": "..."
}'

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.remove_workspace_agent)

POST workspaces/{public_id}/agents/set/ Service tier

POST /api/internal/workspaces/<public_id>/agents/set/

Idempotently registers a Matter agent as a member_type='agent' member of the workspace under its synthetic reserved-domain identity. Body: {agent_public_id, name, avatar_url?}. Unlike human members no org Membership is required: the agent's authority is the calling service (Matter), which is itself org-scoped; and agents hold no seats, so no AppAccess is created (the Premier dual check's seat leg exempts member_type='agent' rows app-side).

This read is not paginated. It returns at most 30 rows and does not report a total, so a result of exactly 30 may be truncated.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/agents/set/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
agent_public_idoptional or conditionalnone
avatar_urloptional 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)

{
  "ok": true,
  "created": true,
  "email": "...",
  "user_id": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400agent_public_id_required
400invalid_json
404workspace_not_found

Example

curl -X POST "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/agents/set/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_public_id": "...",
  "avatar_url": "...",
  "name": "..."
}'

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.set_workspace_agent)

POSTDELETE workspaces/{public_id}/icon/ User API

POST / DELETE /api/workspaces/<public_id>/icon/ : the icon image.

POST takes a multipart image; it is re-encoded and stored with the workspace (workspace_icon.py). DELETE goes back to the letter tile. Same permission as editing the workspace.

URL

  • User APIhttps://auth.mattering.io/api/workspaces/{public_id}/icon/

Path parameters

NameType
public_idstr

Responses

200 bare JSON object (no envelope)

{
  "...": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X POST "https://auth.mattering.io/api/workspaces/PUBLIC_ID/icon/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN"

Source: mattering_auth/workspace_views.py (workspace_views.WorkspaceIconView)

POSTDELETE workspaces/{public_id}/icon/ Service tier

POST / DELETE /api/internal/workspaces/<public_id>/icon/

POST sets the workspace's icon image from a multipart image part or a raw image/* body; DELETE removes it. Both answer the workspace. Caller-trusted like the rest of this module: the calling app has already decided the person may edit the workspace.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/icon/

Path parameters

NameType
public_idstr

Responses

200 bare JSON object (no envelope)

{
  "ok": true,
  "workspace": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404workspace_not_found

Example

curl -X POST "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/icon/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.workspace_icon)

GET workspaces/{public_id}/members/ Service tier

GET /api/internal/workspaces/<public_id>/members/

Returns {"members": [{user_id, email, name, role, is_active}]} for the workspace. Apps use this instead of maintaining local membership tables (platform-wide workspaces thin-mirror).

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/members/

Path parameters

NameType
public_idstr

Responses

200 bare JSON object (no envelope)

{
  "members": [
    {
      "user_id": "...",
      "email": "...",
      "name": "...",
      "role": "...",
      "is_active": true,
      "member_type": "...",
      "is_agent": true,
      "avatar_url": "..."
    }
  ]
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404workspace_not_found

Example

curl -X GET "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/members/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.list_workspace_members)

GETPOSTDELETE workspaces/{public_id}/members/ User API

GET / POST / DELETE /api/workspaces/<public_id>/members/.

URL

  • User APIhttps://auth.mattering.io/api/workspaces/{public_id}/members/

Path parameters

NameType
public_idstr

Query parameters

NameDefault
user_idnone

Body keys (JSON)

KeyRequiredDefault
roleoptional or conditionalnone
user_idoptional 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)

[
  {
    "user_id": "...",
    "email": "...",
    "role": "...",
    "joined_at": "2026-01-01T00:00:00Z"
  }
]

200 bare JSON object (no envelope)

{
  "success": true,
  "user_id": "...",
  "role": "..."
}

400 bare JSON object (no envelope)

...

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400Target user is not a member of this organization message
400last_owner
403forbidden
404Workspace not found message

Example

curl -X POST "https://auth.mattering.io/api/workspaces/PUBLIC_ID/members/" \
  -H "Authorization: Bearer $MATTERING_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "...",
  "user_id": "..."
}'

Source: mattering_auth/workspace_views.py (workspace_views.WorkspaceMemberView)

GET workspaces/{public_id}/members/check/ Service tier

GET /api/internal/workspaces/<public_id>/members/check/?user_id=&email=

Identity-flexible variant of the membership check: callers pass either an auth user_id or an email (apps whose local user pks don't match auth's resolve by email). Same response contract as the path-based check, plus the resolved auth user_id.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/members/check/

Path parameters

NameType
public_idstr

Query parameters

NameDefault
emailnone
user_idnone

Responses

200 bare JSON object (no envelope)

{
  "is_member": true,
  "role": "admin",
  "public_id": "...",
  "user_id": "...",
  "via": "org_admin"
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404workspace_not_found

Example

curl -X GET "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/members/check/?email=...&user_id=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.workspace_membership_check_flex)

POST workspaces/{public_id}/members/remove/ Service tier

POST /api/internal/workspaces/<public_id>/members/remove/

Deactivates a membership (soft delete keeps the audit trail). Body: {user_id (int) OR email (str)}. Removing an owner-ROLE member is rejected with 400 {'error': 'last_owner'} unless another active owner-role member remains (role-based check, not the legacy Workspace.owner_id field). Legacy workspaces with no owner-role member at all allow the removal with a warning log.

Caller-trusted (see module docstring): no actor hierarchy here.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/members/remove/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
emailoptional or conditionalnone
user_idoptional 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)

{
  "ok": true,
  "removed": false,
  "note": "user_not_found"
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
400last_owner
400user_id or email is required message
404workspace_not_found

Example

curl -X POST "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/members/remove/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "...",
  "user_id": "..."
}'

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.remove_workspace_member)

POST workspaces/{public_id}/members/set/ Service tier

POST /api/internal/workspaces/<public_id>/members/set/

Idempotently add a member or update their role. Body: {user_id (int) OR email (str), role (optional, default 'editor')}. The user must hold an active org Membership for the workspace's org.

Caller-trusted (see module docstring): no actor hierarchy is enforced, but the role must be valid and the change may not demote the last active owner-role member of an active workspace.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/members/set/

Path parameters

NameType
public_idstr

Body keys (JSON)

KeyRequiredDefault
emailoptional or conditionalnone
roleoptional or conditionalnone
user_idoptional 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)

{
  "ok": true,
  "created": true,
  "user_id": "...",
  "role": "..."
}

400 bare JSON object (no envelope)

...

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
400last_owner
400reserved_agent_identity
400user_id or email is required message
404user_not_found
404workspace_not_found
409user_not_in_organization

Example

curl -X POST "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/members/set/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "...",
  "role": "...",
  "user_id": "..."
}'

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.set_workspace_member)

GET workspaces/{public_id}/members/{user_id}/ Service tier

GET /api/internal/workspaces/<public_id>/members/<int:user_id>/

* 200 {is_member: true, role, public_id, user_id} * 200 {is_member: false, ...} when no active membership (org admins are treated as implicit members so app-side scoping matches the UI). * 404 when the workspace does not exist.

URL

  • Service tierhttps://auth.mattering.io/api/internal/workspaces/{public_id}/members/{user_id}/

Path parameters

NameType
public_idstr
user_idint

Responses

200 bare JSON object (no envelope)

{
  "is_member": true,
  "role": "admin",
  "public_id": "...",
  "user_id": 0,
  "via": "org_admin"
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404workspace_not_found

Example

curl -X GET "https://auth.mattering.io/api/internal/workspaces/PUBLIC_ID/members/USER_ID/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: mattering_auth/internal_workspace_views.py (internal_workspace_views.workspace_membership_check)

All Auth resources
Start Free Explore our Products