Skip to content
Clym

API reference

Roles

Company role definitions.

Find roles

GET

List system and custom roles for the company.

Query parameters:

Name Type Required Description
search string No Search by role name.
code string No Filter by role code.
is_active boolean No Filter by active state.
is_system boolean No Filter system vs custom roles.
custom_type string No Filter by custom role type.
200List of roles.application/json
metaobjectoptional
Pagination metadata for list responses.
Show properties
current_pageintegeroptional
next_pageintegeroptional
Present only when more pages exist.
prev_pageintegeroptional
Present only when current_page > 1.
resultobject[]optional
Show properties
idintegeroptional
codestringoptional
namestringoptional
descriptionstringoptional
Present only when set.
api_permissionsstring[]optional
ui_permissionsstring[]optional
is_activebooleanoptional
property_idsstring[]optional
Property IDs the role is restricted to.
is_systembooleanoptional
True for built-in system roles (read-only).
custom_typestringenumoptional
Entity type (custom roles only).
Possible values: USER API_KEY
company_idstringoptional
Owning company (custom roles only).
access_countintegeroptional
Users/keys assigned to this role.
created_atstringoptional
Present for custom roles only.
get/admin/company/roles
GET /api/admin/company/roles HTTP/1.1
Host: {instance}.clym.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200List of roles.
{
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": 1
  },
  "result": [{
    "id": 0,
    "code": "string",
    "name": "string",
    "description": "string",
    "api_permissions": ["string"],
    "ui_permissions": ["string"],
    "is_active": false,
    "property_ids": ["string"],
    "is_system": false,
    "custom_type": "USER",
    "company_id": "string",
    "access_count": 0,
    "created_at": "string"
  }]
}

Create role

POST

Create a custom role.

Request bodyapplication/json
codestringoptional
Unique role code. Required on create; ignored on update.
namestringoptional
Role display name. Required on create.
descriptionstringnullableoptional
custom_typestringenumoptional
Entity type. Required on create; ignored on update.
Possible values: USER API_KEY
is_activebooleanoptional
api_permissionsstring[]optional
API permission strings (e.g. 'r:api.admin.company.read'). Required on create.
ui_permissionsstring[]optional
UI permission strings (e.g. 'w:admin.dashboard'). Required when `custom_type` is `USER`.
property_idsstring[]optional
Restrict role to these property IDs.
200Created role.application/json
resultobjectoptional
A company role.
Show properties
idintegeroptional
codestringoptional
namestringoptional
descriptionstringoptional
Present only when set.
api_permissionsstring[]optional
ui_permissionsstring[]optional
is_activebooleanoptional
property_idsstring[]optional
Property IDs the role is restricted to.
is_systembooleanoptional
True for built-in system roles (read-only).
custom_typestringenumoptional
Entity type (custom roles only).
Possible values: USER API_KEY
company_idstringoptional
Owning company (custom roles only).
access_countintegeroptional
Users/keys assigned to this role.
created_atstringoptional
Present for custom roles only.
post/admin/company/roles
POST /api/admin/company/roles HTTP/1.1
Host: {instance}.clym.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

{
  "code": "string",
  "name": "string",
  "description": "string",
  "custom_type": "USER",
  "is_active": false,
  "api_permissions": [
    "string"
  ],
  "ui_permissions": [
    "string"
  ],
  "property_ids": [
    "string"
  ]
}
200Created role.
{
  "result": {
    "id": 0,
    "code": "string",
    "name": "string",
    "description": "string",
    "api_permissions": ["string"],
    "ui_permissions": ["string"],
    "is_active": false,
    "property_ids": ["string"],
    "is_system": false,
    "custom_type": "USER",
    "company_id": "string",
    "access_count": 0,
    "created_at": "string"
  }
}

Get permissions

GET

List assignable system permissions.

200Hierarchical permissions list.application/json
resultobjectoptional
Show properties
api_permissionsobject[]optional
Show properties
groupstringoptional
itemsobject[]optional
Show properties
namestringoptional
endpointobjectoptional
Show properties
methodstringoptional
urlstringoptional
permissionstringoptional
r=read, w=write, s=super
get/admin/company/roles/permissions
GET /api/admin/company/roles/permissions HTTP/1.1
Host: {instance}.clym.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200Hierarchical permissions list.
{
  "result": {
    "api_permissions": [{
      "group": "string",
      "items": [{
        "name": "string",
        "endpoint": {
          "method": {},
          "url": {}
        },
        "permission": "string"
      }]
    }]
  }
}

Read role

GET

Get a role by ID.

Path parameters:

Name Type Required Description
id string Yes The role ID.
200Role details.application/json
resultobjectoptional
A company role.
Show properties
idintegeroptional
codestringoptional
namestringoptional
descriptionstringoptional
Present only when set.
api_permissionsstring[]optional
ui_permissionsstring[]optional
is_activebooleanoptional
property_idsstring[]optional
Property IDs the role is restricted to.
is_systembooleanoptional
True for built-in system roles (read-only).
custom_typestringenumoptional
Entity type (custom roles only).
Possible values: USER API_KEY
company_idstringoptional
Owning company (custom roles only).
access_countintegeroptional
Users/keys assigned to this role.
created_atstringoptional
Present for custom roles only.
get/admin/company/roles/{id}
GET /api/admin/company/roles/{id} HTTP/1.1
Host: {instance}.clym.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200Role details.
{
  "result": {
    "id": 0,
    "code": "string",
    "name": "string",
    "description": "string",
    "api_permissions": ["string"],
    "ui_permissions": ["string"],
    "is_active": false,
    "property_ids": ["string"],
    "is_system": false,
    "custom_type": "USER",
    "company_id": "string",
    "access_count": 0,
    "created_at": "string"
  }
}

Update role

PUT

Update a custom role.

Path parameters:

Name Type Required Description
id string Yes The role ID.
Request bodyapplication/json
codestringoptional
Unique role code. Required on create; ignored on update.
namestringoptional
Role display name. Required on create.
descriptionstringnullableoptional
custom_typestringenumoptional
Entity type. Required on create; ignored on update.
Possible values: USER API_KEY
is_activebooleanoptional
api_permissionsstring[]optional
API permission strings (e.g. 'r:api.admin.company.read'). Required on create.
ui_permissionsstring[]optional
UI permission strings (e.g. 'w:admin.dashboard'). Required when `custom_type` is `USER`.
property_idsstring[]optional
Restrict role to these property IDs.
200Change status.application/json
resultobjectoptional
Show properties
changedstring[]optional
Names of fields that changed; empty/false when nothing changed.
put/admin/company/roles/{id}
PUT /api/admin/company/roles/{id} HTTP/1.1
Host: {instance}.clym.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

{
  "code": "string",
  "name": "string",
  "description": "string",
  "custom_type": "USER",
  "is_active": false,
  "api_permissions": [
    "string"
  ],
  "ui_permissions": [
    "string"
  ],
  "property_ids": [
    "string"
  ]
}
200Change status.
{
  "result": {
    "changed": ["string"]
  }
}

Delete role

DELETE

Delete a custom role; fails if assigned to users.

Path parameters:

Name Type Required Description
id string Yes The role ID.
200Deletion confirmation.application/json
resultobjectoptional
Show properties
deletedbooleanoptional
delete/admin/company/roles/{id}
DELETE /api/admin/company/roles/{id} HTTP/1.1
Host: {instance}.clym.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200Deletion confirmation.
{
  "result": {
    "deleted": false
  }
}

© 2026 ClymTermsPrivacy policyCookie policy