Role

These endpoints let you manage roles in the system.

Get Roles

get

Return the roles.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pageintegerOptional

Page number

Default: 0Example: 0

sizeinteger · min: 1 · max: 50Optional

Page size

Default: 10Example: 10

querystringOptional

Search query

Supported Keys	Supported Operators	Notes
id	:	Equal operator Support multiple values with each value separated by the ; delimiter
name	:	Like operator

Example: {"summary":"Search a role by name","value":"name:admin"}

Responses

200

OK

application/json

totalPagesintegerRequired

Total number of pages available

lastbooleanRequired

Indicates whether this is the last page

totalElementsintegerRequired

Total number of elements across all pages

numberOfElementsintegerRequired

Number of elements in the current page

firstbooleanRequired

Indicates whether this is the first page

sizeintegerRequired

Size of the page (number of elements per page)

numberintegerRequired

Current page number (zero-indexed)

400

Bad Request

get

/v1/roles

cURLPython SDK

curl -X GET \
  "https://api.catapa.com/v1/roles?page=0&size=10&query=name%3Aadmin" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Tenant: your-tenant-id"

{
  "content": [
    {
      "id": "8742a724-0a64-4b1f-92c9-cbcce0c15a92",
      "name": "System Admin"
    }
  ],
  "totalPages": 1,
  "last": true,
  "totalElements": 1,
  "numberOfElements": 1,
  "sort": [
    {
      "direction": "DESC",
      "property": "name",
      "ignoreCase": false,
      "nullHandling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "first": true,
  "size": 10,
  "number": 0
}

Get Role by Id

get

Return the role by Id.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Role ID

Example: 8742a724-0a64-4b1f-92c9-cbcce0c15a92

Responses

200

OK

application/json

idstringOptional

Role identifier

namestringOptional

Role name

descriptionstringOptional

Role description

roleTypestring · enumOptional

Type of role

Possible values:

cascadeOrganizationPermissionbooleanOptional

Whether organization permissions cascade to child organizations

400

Bad Request

404

Role not found

get

/v1/roles/{id}

cURLPython SDK

curl -X GET \
  "https://api.catapa.com/v1/roles/8742a724-0a64-4b1f-92c9-cbcce0c15a92" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Tenant: your-tenant-id"

{
  "id": "8742a724-0a64-4b1f-92c9-cbcce0c15a92",
  "name": "System Admin",
  "description": "Full access to system",
  "roleType": "ADMIN",
  "cascadeOrganizationPermission": true,
  "authorities": [
    {
      "id": "575edda4-dc6d-4d66-9f5d-24a34dbe9d41",
      "code": "AUTH_USER_MANAGEMENT",
      "name": "User Management",
      "description": "Manage Users",
      "moduleName": "System"
    },
    {
      "id": "1ed85f62-9c57-44f2-a78e-8ae41e5c6416",
      "code": "AUTH_ROLE_MANAGEMENT",
      "name": "Role Management",
      "description": "Manage Roles",
      "moduleName": "System"
    }
  ]
}

Get Role Authorities

get

Return the role authorities.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Role ID

Example: 8742a724-0a64-4b1f-92c9-cbcce0c15a92

Query parameters

pageintegerOptional

Page number

Default: 0Example: 0

sizeinteger · min: 1 · max: 50Optional

Page size

Default: 10Example: 10

Responses

200

OK

application/json

totalPagesintegerRequired

Total number of pages available

lastbooleanRequired

Indicates whether this is the last page

totalElementsintegerRequired

Total number of elements across all pages

numberOfElementsintegerRequired

Number of elements in the current page

firstbooleanRequired

Indicates whether this is the first page

sizeintegerRequired

Size of the page (number of elements per page)

numberintegerRequired

Current page number (zero-indexed)

400

Bad Request

404

Role not found

get

/v1/roles/{id}/authorities

cURLPython SDK

curl -X GET \
  "https://api.catapa.com/v1/roles/8742a724-0a64-4b1f-92c9-cbcce0c15a92/authorities?page=0&size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Tenant: your-tenant-id"

{
  "content": [
    {
      "code": "AUTH_USER_MANAGEMENT"
    },
    {
      "code": "AUTH_ROLE_MANAGEMENT"
    }
  ],
  "pageable": {
    "sort": [
      {
        "direction": "ASC",
        "property": "code"
      }
    ],
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 10,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 2,
  "totalPages": 1,
  "last": true,
  "size": 10,
  "number": 0,
  "sort": [
    {
      "direction": "ASC",
      "property": "code"
    }
  ],
  "numberOfElements": 2,
  "first": true
}

Get Role Permissions

get

Return the role permissions.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Role ID

Example: 8742a724-0a64-4b1f-92c9-cbcce0c15a92

Query parameters

expandedbooleanOptional

Controls how permissions are returned:

• false (default): Returns raw permissions as stored in the database without any transformation. Permissions with dataId="ALL" will be returned as-is.
• true: Returns expanded permissions where:
  1. Roles with ADMIN type will get all available dataId permissions
  2. Any permission with dataId="ALL" will be expanded to show all available dataId permissions for the same dataType

Raw permissions show the exact database records, while expanded permissions show the effective access granted to the role after applying permission inheritance rules.

Default: falseExample: false

Responses

200

OK

application/json

400

Bad Request

404

Role not found

get

/v1/roles/{id}/permissions

cURLPython SDK

curl -X GET \
  "https://api.catapa.com/v1/roles/8742a724-0a64-4b1f-92c9-cbcce0c15a92/permissions?expanded=False" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Tenant: your-tenant-id"

{
  "content": [
    {
      "id": "575edda4-dc6d-4d66-9f5d-24a34dbe9d41",
      "dataId": "2f9b85af-4465-433b-bb30-c3702ba8f748",
      "dataType": "ORGANIZATION",
      "role": {
        "id": "8742a724-0a64-4b1f-92c9-cbcce0c15a92",
        "name": "System Admin"
      }
    },
    {
      "id": "1ed85f62-9c57-44f2-a78e-8ae41e5c6416",
      "dataId": "e3d5c440-cb02-4f47-a4ce-9c8e3d7e682b",
      "dataType": "LOCATION",
      "role": {
        "id": "8742a724-0a64-4b1f-92c9-cbcce0c15a92",
        "name": "System Admin"
      }
    }
  ]
}