Skip to content

Roles

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}/clone_to_customer/ Clone a role into an organization
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
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.role_details_field_enum import RoleDetailsFieldEnum # (1)
from waldur_api_client.models.role_details_o_enum import RoleDetailsOEnum # (2)
from waldur_api_client.api.roles import roles_list # (3)

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. Model Source: RoleDetailsFieldEnum
  2. Model Source: RoleDetailsOEnum
  3. 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
available_for_customer string (uuid) Roles usable within a customer (uuid): system roles + org-private, minus concealed
content_type string Comma-separated scope types (e.g. 'customer,project') to keep.
description string
field array
include_concealed boolean Keep roles concealed for the customer in the available_for_customer result (staff management view).
is_active boolean
is_system_role boolean
name string
o array Ordering
page integer A page number within the paginated result set.
page_size integer Number of results to return per page.
query string Search by role name or description.

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
description_km string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any
template_uuid string
template_name string
customer_uuid string (uuid)
customer_name string

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
13
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.role_details_field_enum import RoleDetailsFieldEnum # (1)
from waldur_api_client.api.roles import roles_retrieve # (2)

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. Model Source: RoleDetailsFieldEnum
  2. 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
description_km string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any
template_uuid string
template_name string
customer_uuid string (uuid)
customer_name string

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:='{}' \
  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={},
    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": {},
    "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
description_km string
permissions object (free-form) ✓
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
description_km string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any
template_uuid string
template_name string
customer_uuid string (uuid)
customer_name string

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:='{}' \
  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={},
    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": {},
    "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
description_km string
permissions object (free-form) ✓
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
description_km string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any
template_uuid string
template_name string
customer_uuid string (uuid)
customer_name string

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
description_km 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
description_km 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
description_km 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
description_km string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any
template_uuid string
template_name string
customer_uuid string (uuid)
customer_name string

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

Clone a role into an organization

Staff-only. Creates an organization-private copy of this role (customer or project scope), bound to the given customer and usable only within that organization and its projects. Cloning the same template into the same organization twice is rejected.

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

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

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

body_data = RoleCloneRequest(
    customer="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
)
response = roles_clone_to_customer.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client,
    body=body_data
)

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

try {
  const response = await rolesCloneToCustomer({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  body: {
    "customer": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Field Type Required
customer string (uuid) ✓
description string
conceal_template 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
description_km string
permissions array of strings
is_system_role boolean
is_active boolean
users_count integer
content_type any
template_uuid string
template_name string
customer_uuid string (uuid)
customer_name string

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.