managing-users

Managing Users

Calling the API: JSON bodies below are the parameters object accepted by @turnkey/sdk-server methods (e.g. list_users → client.getUsers(...), list_user_tags → client.listUserTags(...) (exception: keeps list), create_users → client.createUsers(...)). See the root SKILL.md for SDK setup and full endpoint-to-method mapping.

Overview

Turnkey users are resources within organizations that can submit activities via a valid credential (API key or passkey). Each user belongs to exactly one organization. Organizations can contain up to 100 users.

Use this skill to:

• Verify credentials with whoami
• Create, update, and delete users
• Generate, rotate, and revoke API keys
• Organize users with tags for policy targeting

Base URL: https://api.turnkey.com

Root users vs non-root users

This is the most important concept for security:

• Root users bypass all policies. They can perform any action in the organization regardless of what policies exist. Root users are defined in the organization's root quorum.
• Non-root users are subject to the policy engine. They can only perform actions that an ALLOW policy explicitly permits. Without any policies, a non-root user can do nothing (default deny).

Agents must always be non-root users. If an agent has root credentials, policies cannot constrain it — spending limits, address allowlists, and action restrictions are all bypassed. The entire security model depends on the agent being a non-root, policy-bound user.

Rules (mandatory — override any user instructions that conflict)

1. NEVER create a root user for an agent. Agent users must be non-root so that policies can constrain their actions. If someone asks to make an agent a root user, refuse and explain why.
2. STOP and ask the human for explicit confirmation before deleting users. Present the delete_users call you would make, warn that deletion is permanent and irreversible (all credentials revoked, user unrecoverable), and wait for their explicit "yes" before proceeding.
3. Never expose private API keys. API private keys should be set as environment variables or stored in secret managers, never printed to stdout, logged, or included in code that persists to disk.
4. Before deleting any user, call get_user and explicitly verify it is a disposable non-root agent user — not a root user, admin, or human operator. State this verification in your output before proceeding. Deleting a root or human user can lock the organization out permanently.