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
Name
Default
organization_id
none
Body keys (JSON)
Key
Required
Default
color
optional or conditional
none
description
optional or conditional
none
name
optional or conditional
none
organization_id
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.
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)
Key
Required
Default
color
optional or conditional
none
description
optional or conditional
none
icon_letter
optional or conditional
none
members
optional or conditional
none
name
optional or conditional
none
order
optional or conditional
none
organization_id
optional or conditional
none
owner_email
optional or conditional
none
owner_user_id
optional or conditional
none
public_id
optional or conditional
none
seed
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
200bare JSON object (no envelope)
{
"created": true,
"workspace": "..."
}
400bare JSON object (no envelope)
...
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
User APIhttps://auth.mattering.io/api/workspaces/{public_id}/
Path parameters
Name
Type
public_id
str
Body keys (JSON)
Key
Required
Default
icon_letter
optional or conditional
none
name
optional or conditional
none
order
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
200bare JSON object (no envelope)
{
"...": "..."
}
200bare 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
Status
Code
400
Workspace name is requiredmessage
403
You do not have permission to delete this workspacemessage
403
You do not have permission to edit this workspacemessage
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
Name
Type
public_id
str
Body keys (JSON)
Key
Required
Default
agent_public_id
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
200bare 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).
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
Name
Type
public_id
str
Body keys (JSON)
Key
Required
Default
agent_public_id
optional or conditional
none
avatar_url
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.
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
Name
Type
public_id
str
Responses
200bare 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"
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
Name
Type
public_id
str
Responses
200bare 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).
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/
GETPOSTDELETEworkspaces/{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
Name
Type
public_id
str
Query parameters
Name
Default
user_id
none
Body keys (JSON)
Key
Required
Default
role
optional or conditional
none
user_id
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.
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/
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
Name
Type
public_id
str
Body keys (JSON)
Key
Required
Default
email
optional or conditional
none
user_id
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.
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
Name
Type
public_id
str
Body keys (JSON)
Key
Required
Default
email
optional or conditional
none
role
optional or conditional
none
user_id
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.
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}/
We use strictly necessary cookies to run this site. With your permission we also use analytics cookies
(Google Analytics and our own visit tracking) to see which pages work. Read the
Cookie notice.