Skip to content

Roles

Roles are named collections of permissions that define what a user is allowed to do within a specific scope (either a Customer or a Project). They are the cornerstone of the platform's Role-Based Access Control (RBAC) system.

A user's effective permissions are determined by the combination of their assigned role and the scope to which it applies.

The Permission Triplet

Access control is defined by a triplet: (User, Role, Scope).

  • User: Who is performing the action?

  • Role: What can they do? (e.g., Project Administrator, Customer Owner)

  • Scope: Where can they do it? (e.g., on "Project Alpha" or across the entire "Customer Inc.")

Operations Summary

Method Endpoint Description
Core CRUD
GET /api/roles/ List roles
GET /api/roles/{uuid}/ Get role details
POST /api/roles/ Create a new role
PUT /api/roles/{uuid}/ Update a role
PUT /api/roles/{uuid}/update_descriptions/ Update role descriptions
PATCH /api/roles/{uuid}/ Partial Update
DELETE /api/roles/{uuid}/ Delete a role
Other Actions
POST /api/roles/{uuid}/disable/ Disable a role
POST /api/roles/{uuid}/enable/ Enable a role

Core CRUD

List roles

Get a list of all available roles.

1
2
3
4
http \
  GET \
  https://api.example.com/api/roles/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.roles import roles_list # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = roles_list.sync(client=client)

for item in response:
    print(item)
  1. API Source: roles_list
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { rolesList } from 'waldur-js-client';

try {
  const response = await rolesList({
  auth: "Token YOUR_API_TOKEN"
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Description
description string
field array
is_active boolean
name string
page integer A page number within the paginated result set.
page_size integer Number of results to return per page.

200 -

The response body is an array of objects, where each object has the following structure:

Field Type
uuid string (uuid)
name string
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any

Get role details

Retrieve the details of a specific role by its UUID.

1
2
3
4
http \
  GET \
  https://api.example.com/api/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.roles import roles_retrieve # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = roles_retrieve.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: roles_retrieve
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { rolesRetrieve } from 'waldur-js-client';

try {
  const response = await rolesRetrieve({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Name Type
field array

200 -

Field Type
uuid string (uuid)
name string
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any

Create a new role

Allows staff users to create a new custom role with a specific set of permissions.

1
2
3
4
5
6
7
http \
  POST \
  https://api.example.com/api/roles/ \
  Authorization:"Token YOUR_API_TOKEN" \
  name="my-awesome-role" \
  permissions=null \
  content_type="string-value"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.role_modify_request import RoleModifyRequest # (1)
from waldur_api_client.api.roles import roles_create # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = RoleModifyRequest(
    name="my-awesome-role",
    permissions=null,
    content_type="string-value"
)
response = roles_create.sync(
    client=client,
    body=body_data
)

print(response)
  1. Model Source: RoleModifyRequest
  2. API Source: roles_create
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { rolesCreate } from 'waldur-js-client';

try {
  const response = await rolesCreate({
  auth: "Token YOUR_API_TOKEN",
  body: {
    "name": "my-awesome-role",
    "permissions": null,
    "content_type": "string-value"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Field Type Required
name string ✓
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
permissions any ✓
is_active boolean
content_type string ✓

201 -

Field Type
uuid string (uuid)
name string
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any

Update a role

Allows staff users to update an existing role's name, description, content type, and permissions. The name of a system role cannot be changed.

1
2
3
4
5
6
7
http \
  PUT \
  https://api.example.com/api/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  Authorization:"Token YOUR_API_TOKEN" \
  name="my-awesome-role" \
  permissions=null \
  content_type="string-value"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.role_modify_request import RoleModifyRequest # (1)
from waldur_api_client.api.roles import roles_update # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = RoleModifyRequest(
    name="my-awesome-role",
    permissions=null,
    content_type="string-value"
)
response = roles_update.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client,
    body=body_data
)

print(response)
  1. Model Source: RoleModifyRequest
  2. API Source: roles_update
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import { rolesUpdate } from 'waldur-js-client';

try {
  const response = await rolesUpdate({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  body: {
    "name": "my-awesome-role",
    "permissions": null,
    "content_type": "string-value"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Field Type Required
name string ✓
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
permissions any ✓
is_active boolean
content_type string ✓

200 -

Field Type
uuid string (uuid)
name string
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any

Update role descriptions

Allows staff users to update the multilingual descriptions of a role.

1
2
3
4
http \
  PUT \
  https://api.example.com/api/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update_descriptions/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.role_description_request import RoleDescriptionRequest # (1)
from waldur_api_client.api.roles import roles_update_descriptions_update # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = RoleDescriptionRequest()
response = roles_update_descriptions_update.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client,
    body=body_data
)

print(response)
  1. Model Source: RoleDescriptionRequest
  2. API Source: roles_update_descriptions_update
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { rolesUpdateDescriptionsUpdate } from 'waldur-js-client';

try {
  const response = await rolesUpdateDescriptionsUpdate({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Field Type Required
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string

200 -

Field Type
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string

Partial Update

1
2
3
4
http \
  PATCH \
  https://api.example.com/api/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.patched_role_details_request import PatchedRoleDetailsRequest # (1)
from waldur_api_client.api.roles import roles_partial_update # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = PatchedRoleDetailsRequest()
response = roles_partial_update.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client,
    body=body_data
)

print(response)
  1. Model Source: PatchedRoleDetailsRequest
  2. API Source: roles_partial_update
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { rolesPartialUpdate } from 'waldur-js-client';

try {
  const response = await rolesPartialUpdate({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Field Type Required
name string
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
is_active boolean

200 -

Field Type
uuid string (uuid)
name string
description string
description_en string
description_et string
description_lt string
description_lv string
description_ru string
description_it string
description_de string
description_da string
description_sv string
description_es string
description_fr string
description_nb string
description_ar string
description_cs string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any

Delete a role

Allows staff users to delete a custom role. System roles and roles that are currently in use cannot be deleted.

1
2
3
4
http \
  DELETE \
  https://api.example.com/api/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.roles import roles_destroy # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = roles_destroy.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: roles_destroy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { rolesDestroy } from 'waldur-js-client';

try {
  const response = await rolesDestroy({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓

204 - No response body

Other Actions

Disable a role

Allows staff users to disable a role, preventing it from being assigned further. Existing assignments are not affected.

1
2
3
4
http \
  POST \
  https://api.example.com/api/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/disable/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.roles import roles_disable # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = roles_disable.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: roles_disable
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { rolesDisable } from 'waldur-js-client';

try {
  const response = await rolesDisable({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓

200 - Role disabled successfully.

Enable a role

Allows staff users to enable a role, making it available for assignment.

1
2
3
4
http \
  POST \
  https://api.example.com/api/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890/enable/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.roles import roles_enable # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = roles_enable.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: roles_enable
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { rolesEnable } from 'waldur-js-client';

try {
  const response = await rolesEnable({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓

200 - Role enabled successfully.