List roles

Lists the workspace's roles with their system permissions, record type grants and whether any member holds them, as the Roles settings page and the roles of the MCP get_workspace_context tool show them. Supports searchTerm on the name, sortDescriptor with field type (system roles first, then by name) and pagination. Read one role with its record type catalog through /v1/roles/read, and assign a role to a member through /v1/members/update.

Requires: read access to users; without role management (edit access to users) only the caller's own role is listed.

POST
/v1/roles/list

Authorization

apiKeyAuth
x-api-key<token>

API key authentication. Create an API key in your user profile and include it in the x-api-key header.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://customermates.com/api/v1/roles/list" \  -H "Content-Type: application/json" \  -d '{    "pagination": {      "page": 1,      "pageSize": 25    }  }'
{
  "p13nId": "string",
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "isSystemRole": true,
      "createdAt": "string",
      "updatedAt": "string",
      "permissions": [
        {
          "id": "string",
          "resource": "dataModel",
          "action": "create"
        }
      ],
      "recordGrants": [
        {
          "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7",
          "actions": [
            "create"
          ]
        }
      ],
      "hasUsersAssigned": true
    }
  ],
  "filters": [
    null
  ],
  "searchTerm": "string",
  "sortDescriptor": null,
  "pagination": {
    "page": 0,
    "pageSize": 0,
    "totalPages": 0,
    "total": 0
  },
  "filterableFields": [
    null
  ],
  "columnOrder": [
    "string"
  ],
  "columnWidths": {
    "property1": 0,
    "property2": 0
  },
  "hiddenColumns": [
    "string"
  ],
  "viewMode": "string",
  "groupCounts": {
    "property1": 0,
    "property2": 0
  },
  "views": [
    null
  ],
  "activeViewKey": "string",
  "allState": null,
  "viewPersistable": true,
  "grouping": null,
  "groupableFields": [
    null
  ]
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
Empty