RBAC API: roles, assignments, and host sharing

The RBAC API provides role-based access control for Termix resources. You can create custom roles, assign them to users, and share individual hosts and snippets with specific users or roles. All endpoints require JWT authentication. Role creation, update, deletion, and user-role assignments additionally require admin privileges.

Roles

List all roles

GET /rbac/roles Returns all roles, both system-defined and custom.

roles

object[]

Array of role objects.

Show properties

number

Role ID.

name

string

Unique machine-readable name (lowercase, numbers, underscores, hyphens).

displayName

string

Human-readable display name.

description

string

Optional description.

isSystem

boolean

Whether this is a built-in role (admin, user) that cannot be modified or deleted.

createdAt

string

ISO 8601 timestamp.

updatedAt

string

ISO 8601 timestamp.

Example request

cURL

curl -X GET https://your-termix-host/rbac/roles \
  -H "Authorization: Bearer <token>"

Example response (200)

{
  "roles": [
    {
      "id": 1,
      "name": "admin",
      "displayName": "Administrator",
      "isSystem": true
    },
    {
      "id": 3,
      "name": "devops",
      "displayName": "DevOps Team",
      "description": "Access to production servers",
      "isSystem": false
    }
  ]
}

Create a role

POST /rbac/roles

Requires admin privileges.

name

string

required

Unique machine-readable name. Only lowercase letters, numbers, underscores, and hyphens are allowed.

displayName

string

required

Human-readable display name shown in the UI.

description

string

Optional description of the role’s purpose.

success

boolean

Always true on success.

roleId

number

ID of the newly created role.

message

string

Confirmation message.

Error responses

Status	Meaning
400	`name` or `displayName` missing, or `name` contains invalid characters.
401	Authentication required.
403	Admin privileges required.
409	A role with this name already exists.
500	Database error.

Example request

cURL

curl -X POST https://your-termix-host/rbac/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "devops", "displayName": "DevOps Team", "description": "Access to production servers"}'

Update a role

PUT /rbac/roles/:id

Requires admin privileges.

number

required

Role ID.

displayName

string

New display name.

description

string

New description. Pass empty string to clear.

Error responses

Status	Meaning
400	Invalid role ID, or neither `displayName` nor `description` provided.
401	Authentication required.
403	Admin privileges required.
404	Role not found.
500	Database error.

Example request

cURL

curl -X PUT https://your-termix-host/rbac/roles/3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "DevOps Engineers"}'

Delete a role

DELETE /rbac/roles/:id

Requires admin privileges. System roles (isSystem: true) cannot be deleted.

Deletes the role and removes all user-role and host-access grants associated with it. Permission caches for affected users are invalidated.

number

required

Role ID.

Error responses

Status	Meaning
400	Invalid role ID.
401	Authentication required.
403	Admin privileges required, or the role is a system role.
404	Role not found.
500	Database error.

Example request

cURL

curl -X DELETE https://your-termix-host/rbac/roles/3 \
  -H "Authorization: Bearer <token>"

User-role assignments

Get a user’s roles

GET /rbac/users/:userId/roles

Users can query their own roles. Querying another user’s roles requires admin privileges.

userId

string

required

The target user’s ID.

roles

object[]

Array of assigned role objects with id, roleId, roleName, roleDisplayName, description, isSystem, and grantedAt.

Error responses

Status	Meaning
401	Authentication required.
403	Access denied — cannot view another user’s roles without admin privileges.
500	Database error.

Example request

cURL

curl -X GET https://your-termix-host/rbac/users/user_abc123/roles \
  -H "Authorization: Bearer <token>"

Assign a role to a user

POST /rbac/users/:userId/roles

Requires admin privileges. System roles cannot be manually assigned.

userId

string

required

The target user’s ID.

roleId

number

required

ID of the role to assign.

When a role is assigned, shared credentials are automatically provisioned for all hosts that have been shared with that role.

Error responses

Status	Meaning
400	`roleId` is not a number.
401	Authentication required.
403	Admin privileges required, or the role is a system role.
404	User or role not found.
409	The user already has this role.
500	Database error.

Example request

cURL

curl -X POST https://your-termix-host/rbac/users/user_abc123/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"roleId": 3}'

Remove a role from a user

DELETE /rbac/users/:userId/roles/:roleId

Requires admin privileges. System roles cannot be removed.

userId

string

required

The target user’s ID.

roleId

number

required

The role ID to remove.

Error responses

Status	Meaning
400	Invalid role ID.
401	Authentication required.
403	Admin privileges required, or the role is a system role.
404	Role not found.
500	Database error.

Example request

cURL

curl -X DELETE https://your-termix-host/rbac/users/user_abc123/roles/3 \
  -H "Authorization: Bearer <token>"

Host access

Get host access list

GET /rbac/host/:id/access Returns all users and roles that have been granted access to the specified host. Only the host owner can call this endpoint.

number

required

Host ID.

accessList

object[]

Show properties

number

Access grant ID.

targetType

string

"user" or "role".

userId

string

User ID, present when targetType is "user".

roleId

number

Role ID, present when targetType is "role".

username

string

Username of the grantee, if applicable.

roleName

string

Role name, if applicable.

roleDisplayName

string

Role display name, if applicable.

grantedBy

string

User ID of the person who created the grant.

grantedByUsername

string

Username of the grantor.

permissionLevel

string

Currently always "view".

expiresAt

string

ISO 8601 expiry timestamp, or null for permanent grants.

createdAt

string

ISO 8601 timestamp when the grant was created.

Error responses

Status	Meaning
400	Invalid host ID.
401	Authentication required.
403	The authenticated user does not own the host.
500	Database error.

Example request

cURL

curl -X GET https://your-termix-host/rbac/host/5/access \
  -H "Authorization: Bearer <token>"

POST /rbac/host/:id/share Grants access to a host for a specific user or role. The host must have a credential assigned before it can be shared.

number

required

Host ID.

targetType

string

default:"user"

Who to share with. Either "user" or "role".

targetUserId

string

Required when targetType is "user". The user’s ID.

targetRoleId

number

Required when targetType is "role". The role’s ID.

durationHours

number

Optional. If set, the access grant expires after this many hours.

permissionLevel

string

default:"view"

Permission level. Currently only "view" is supported.

success

boolean

Always true on success.

message

string

Confirmation message.

expiresAt

string

ISO 8601 expiry timestamp, or null for permanent grants.

Error responses

Status	Meaning
400	Invalid `targetType`, missing `targetUserId`/`targetRoleId`, or host has no credential assigned.
401	Authentication required.
403	The authenticated user does not own the host.
404	Target user or role not found.
500	Database error.

Example request

cURL

curl -X POST https://your-termix-host/rbac/host/5/share \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "user",
    "targetUserId": "user_abc123",
    "durationHours": 24
  }'

Revoke host access

DELETE /rbac/host/:id/access/:accessId Removes an access grant. Only the host owner can revoke grants.

number

required

Host ID.

accessId

number

required

Access grant ID (from the access list).

Error responses

Status	Meaning
400	Invalid host ID or access ID.
401	Authentication required.
403	The authenticated user does not own the host.
500	Database error.

Example request

cURL

curl -X DELETE https://your-termix-host/rbac/host/5/access/12 \
  -H "Authorization: Bearer <token>"

List shared hosts

GET /rbac/shared-hosts Returns all hosts shared with the authenticated user that have not yet expired.

sharedHosts

object[]

Show properties

number

Host ID.

name

string

Host name.

string

Host IP address.

port

number

SSH port.

username

string

SSH username.

folder

string

Folder the host is organized in.

Snippet access

Get snippet access list

GET /rbac/snippet/:id/access Returns all users and roles with access to a snippet. Only the snippet owner can call this endpoint.

number

required

Snippet ID.

accessList

object[]

Same structure as the host access list, but without permissionLevel (snippets always grant "view").

POST /rbac/snippet/:id/share Grants access to a snippet for a user or role.

number

required

Snippet ID.

targetType

string

default:"user"

"user" or "role".

targetUserId

string

Required when targetType is "user".

targetRoleId

number

Required when targetType is "role".

durationHours

number

Optional expiry in hours.

Error responses

Status	Meaning
400	Invalid `targetType` or missing target identifier.
401	Authentication required.
403	The authenticated user does not own the snippet.
404	Target user or role not found.
500	Database error.

Example request

cURL

curl -X POST https://your-termix-host/rbac/snippet/42/share \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"targetType": "role", "targetRoleId": 3}'

Revoke snippet access

DELETE /rbac/snippet/:id/access/:accessId

number

required

Snippet ID.

accessId

number

required

Access grant ID.

List shared snippets

GET /rbac/shared-snippets Returns snippets shared with the authenticated user (both directly and via role membership) that have not expired.

sharedSnippets

object[]

Show properties

number

Snippet ID.

name

string

Snippet name.

content

string

Command content.

description

string

Optional description.

folder

string

Folder name or null.

ownerUsername

string

Username of the snippet owner.

permissionLevel

string

Always "view".

expiresAt

string

Expiry timestamp or null.

Example request

cURL

curl -X GET https://your-termix-host/rbac/shared-snippets \
  -H "Authorization: Bearer <token>"

Overview

Endpoints

RBAC API: roles, assignments, and host sharing

Roles

List all roles

Create a role

Update a role

Delete a role

User-role assignments

Get a user’s roles

Assign a role to a user

Remove a role from a user

Host access

Get host access list

Revoke host access

List shared hosts

Snippet access

Get snippet access list

Revoke snippet access

List shared snippets

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Roles

​List all roles

​Create a role

​Update a role

​Delete a role

​User-role assignments

​Get a user’s roles

​Assign a role to a user

​Remove a role from a user

​Host access

​Get host access list

​Share a host

​Revoke host access

​List shared hosts

​Snippet access

​Get snippet access list

​Share a snippet

​Revoke snippet access

​List shared snippets

Build docs developers (and LLMs) love

Roles

List all roles

Create a role

Update a role

Delete a role

User-role assignments

Get a user’s roles

Assign a role to a user

Remove a role from a user

Host access

Get host access list

Share a host

Revoke host access

List shared hosts

Snippet access

Get snippet access list

Share a snippet

Revoke snippet access

List shared snippets