Managing Users and Workspaces

Description

Create and manage users, API keys, and workspaces using CLI tools

Difficulty

Intermediate

Duration

15 min

You will need
  • A running TrustGraph deployment
  • TrustGraph CLI tools installed
  • Admin-level access (API key with admin role)
Goal

Create and manage users, API keys, roles, and workspaces using command-line tools.

Authentication

All commands require a valid authentication token with admin privileges:

export TRUSTGRAPH_TOKEN="tg_my-admin-token"

Users

Check your identity 

tg-whoami

Create a user

Create a new user in the current workspace:

tg-create-user \
  --username alice \
  --name "Alice Smith" \
  --email alice@example.com \
  --roles writer

The command prints the new user ID. If --password is omitted, you will be prompted to enter one.

Available roles:

  • reader — read-only access within the workspace
  • writer — read/write access within the workspace
  • admin — access across all workspaces

You can assign multiple roles:

tg-create-user \
  --username bob \
  --roles reader writer

List users 

tg-list-users

Admins can list users in a specific workspace:

tg-list-users -w my-workspace

Update a user

Update profile fields, roles, or account status:

tg-update-user \
  --user-id <user-id> \
  --name "Alice Jones" \
  --roles reader writer

Disable and enable users

Disabling a user prevents login and revokes all their API keys:

tg-disable-user --user-id <user-id>

Re-enable a previously disabled user:

tg-enable-user --user-id <user-id>

Delete a user

Permanently delete a user and all their API keys:

tg-delete-user --user-id <user-id>

Add --yes to skip the confirmation prompt.

Passwords

Change your own password 

tg-change-password

You will be prompted for your current and new passwords.

Reset a user’s password (admin)

Generate a one-time temporary password for a user:

tg-reset-password --user-id <user-id>

The temporary password is printed to stdout. The user will be required to change it on next login.

API Keys

API keys are long-lived tokens with a tg_ prefix, used for programmatic access, CLI tools, and integrations.

Create an API key 

tg-create-api-key \
  --user-id <user-id> \
  --name "laptop"

The plaintext key is printed to stdout and shown only once — store it securely.

Optionally set an expiry date:

tg-create-api-key \
  --user-id <user-id> \
  --name "ci-pipeline" \
  --expires 2026-12-31T23:59:59Z

List API keys 

tg-list-api-keys --user-id <user-id>

Revoke an API key 

tg-revoke-api-key --key-id <key-id>

Workspaces

Workspaces provide data isolation — each workspace has its own documents, knowledge graphs, collections, and users. See Workspaces & Data Isolation for details.

List workspaces 

tg-list-workspaces

Create a workspace 

tg-create-workspace \
  --workspace-id research \
  --name "Research Team"

Workspace IDs must not start with _.

Login

For interactive use, you can log in with username and password to obtain a temporary JWT token:

tg-login --username alice

The JWT is printed to stdout. You can use it directly:

export TRUSTGRAPH_TOKEN=$(tg-login --username alice)