Workspace Members

Workspaces organize users within a tenant. These endpoints allow you to manage workspace membership, assign roles, and check permissions. Roles determine what actions a member can perform within the workspace.

All workspace member endpoints operate within the context of the current workspace, determined by the authenticated user's active workspace selection.

GET/core/api/v1/workspace/members

List workspace members

Retrieve a list of all members in the current workspace, including their roles and join dates.

Response fields

Name
user_id
Type
string
Description
The UUID of the member.
Name
role
Type
string
Description
The member's role in the workspace. One of owner, editor, or viewer.
Name
joined_at
Type
string
Description
ISO 8601 timestamp of when the member joined the workspace.

GET

/core/api/v1/workspace/members

curl https://your-sphere.example.com/core/api/v1/workspace/members \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "user_id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "role": "owner",
      "joined_at": "2026-01-10T08:00:00Z"
    },
    {
      "user_id": "b2c3d4e5-f6a7-890b-cdef-1234567890ab",
      "role": "editor",
      "joined_at": "2026-01-12T14:30:00Z"
    },
    {
      "user_id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
      "role": "viewer",
      "joined_at": "2026-01-15T09:00:00Z"
    }
  ]
}

POST/core/api/v1/workspace/members

Add workspace member

Add a user to the current workspace with a specified role. The user must already exist within the tenant.

Request body

Name
user_id
Type
string
Description
The UUID of the user to add to the workspace.
Name
role
Type
string
Description
The role to assign. One of owner, editor, or viewer. Defaults to viewer.

POST

/core/api/v1/workspace/members

curl -X POST https://your-sphere.example.com/core/api/v1/workspace/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
    "role": "editor"
  }'

Response

{
  "data": {
    "user_id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
    "role": "editor",
    "joined_at": "2026-02-20T14:00:00Z"
  }
}

PATCH/core/api/v1/workspace/members/{userId}

Change member role

Update the role of an existing workspace member.

Path parameters

Name
userId
Type
string
Description
The UUID of the member whose role to change.

Request body

Name
role
Type
string
Description
The new role to assign. One of owner, editor, or viewer.

PATCH

/core/api/v1/workspace/members/{userId}

curl -X PATCH https://your-sphere.example.com/core/api/v1/workspace/members/c3d4e5f6-a7b8-90cd-ef12-34567890abcd \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer"
  }'

Response

{
  "data": {
    "user_id": "c3d4e5f6-a7b8-90cd-ef12-34567890abcd",
    "role": "viewer",
    "joined_at": "2026-01-15T09:00:00Z"
  }
}

DELETE/core/api/v1/workspace/members/{userId}

Remove workspace member

Remove a member from the current workspace. This does not delete the user from the tenant -- it only revokes their workspace access.

Path parameters

Name
userId
Type
string
Description
The UUID of the member to remove.

DELETE

/core/api/v1/workspace/members/{userId}

curl -X DELETE https://your-sphere.example.com/core/api/v1/workspace/members/c3d4e5f6-a7b8-90cd-ef12-34567890abcd \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Member removed from workspace"
}

GET/core/api/v1/workspace/permissions

Get current permissions

Retrieve the permissions of the currently authenticated user within the active workspace. This is useful for conditionally rendering UI elements based on what the user can do.

Response fields

Name
role
Type
string
Description
The user's role in the workspace (owner, editor, or viewer).
Name
permissions
Type
array
Description
List of permission strings the user has (e.g. entities.create, entities.delete, members.manage).

GET

/core/api/v1/workspace/permissions

curl https://your-sphere.example.com/core/api/v1/workspace/permissions \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "role": "editor",
    "permissions": [
      "entities.view",
      "entities.create",
      "entities.update",
      "relations.view",
      "relations.create",
      "relations.delete",
      "members.view",
      "timeline.view",
      "inbox.view"
    ]
  }
}