knot knot

knot.user

The knot.user library provides user management functions.

Execution Environment

Environment Behaviour
Embedded (MCP tool execution, event sinks, plugin handlers, remote/space scripts, knot run-script) Available; authenticated automatically via the Go-provided knot.apiclient transport.
Health check scripts Not available.
External (standalone scripts) Python implementation; configure knot.apiclient first (or set the KNOT_* environment variables).

Functions

Function Description
list(state='', zone='') List users; state is all (default), active or inactive, and zone defaults to the server’s zone. Each entry has id, username, email, active and number_spaces
get(user_id) Get user by ID or username
get_me() Get the current user
create(username, email, password, active=True, max_spaces=0, compute_units=0, storage_units=0, max_tunnels=0, ssh_public_key='', github_username='') Create a new user and return its ID
update(user_id, username=None, email=None, password=None, active=None, max_spaces=None, ssh_public_key=None, github_username=None) Update user properties; omitted arguments (and roles, groups and other quotas) keep their current values. Returns True
set_ssh_public_key(ssh_public_key, github_username=None) Set the current user’s SSH public keys
set_ssh_private_key(ssh_private_key) Set the current user’s SSH private key
delete(user_id) Delete a user; returns True
link_user(user_id, linked_user_id) Grant user_id the ability to become linked_user_id — one way (requires the link_users permission)
unlink_user(user_id, linked_user_id) Remove linked_user_id from user_id’s become-list (requires the link_users permission)
get_quota(user_id) Get user quota and usage
list_permissions(user_id) List the user’s built-in permissions (integer IDs)
list_plugin_permissions(user_id) List the user’s plugin permissions — qualified grant strings (plugin.<name>.<id>) resolved from their roles
has_permission(user_id, permission_id) Check if user has a specific permission — an integer checks a built-in, a "plugin."-prefixed string checks a plugin grant

Usage

import knot.user as user

# Get current user
me = user.get_me()
print(me['username'])

# List users
users = user.list()
for u in users:
    print(f"{u['username']}: {u['email']}")

# Get a specific user
u = user.get("some-user-id")
print(u['username'])

# Check permissions
if user.has_permission(me['id'], 2):  # MANAGE_SPACES = 2
    print("User can manage spaces")

# Get quota information
quota = user.get_quota(me['id'])
print(f"Spaces: {quota['number_spaces']}/{quota['max_spaces']}")

# Let user A become user B (one way; needs the link_users permission)
user.link_user("user-a-id", "user-b-id")

# Take that ability away again
user.unlink_user("user-a-id", "user-b-id")

# Update SSH keys for the current user
user.set_ssh_public_key("ssh-ed25519 AAAA...")
user.set_ssh_private_key("-----BEGIN OPENSSH PRIVATE KEY-----\n...")

User Properties

get() and get_me() return:

  • id - User ID
  • username - Username
  • email - Email address
  • active - Whether user is active
  • max_spaces - Maximum spaces allowed
  • compute_units - Compute units quota
  • storage_units - Storage units quota
  • max_tunnels - Maximum tunnels allowed
  • preferred_shell - Preferred shell
  • timezone - User timezone
  • github_username - GitHub username
  • ssh_public_key - SSH public keys, one key per line
  • ssh_private_key - SSH private key, only populated for the current user
  • number_spaces - Current number of spaces
  • number_spaces_deployed - Number of running spaces
  • used_compute_units - Used compute units
  • used_storage_units - Used storage units
  • used_tunnels - Used tunnels
  • current - Whether this is the current user
  • roles - List of role IDs
  • groups - List of group IDs
  • linked_users - The accounts this user may become, each with user_id and username

Quota Properties

get_quota() returns:

  • max_spaces - Maximum spaces allowed
  • compute_units - Compute units quota
  • storage_units - Storage units quota
  • max_tunnels - Maximum tunnels allowed
  • number_spaces - Current number of spaces
  • number_spaces_deployed - Number of running spaces
  • used_compute_units - Used compute units
  • used_storage_units - Used storage units
  • used_tunnels - Used tunnels