managing-agent

Managing an Agent

Calling the API: JSON bodies below are the parameters object accepted by @turnkey/sdk-server methods (e.g. create_api_keys → client.createApiKeys(...), update_policy → client.updatePolicy(...)). See the root SKILL.md for SDK setup and full endpoint-to-method mapping.

Independent recipes for day-2 agent operations. Each section is self-contained — find the one that matches your situation.

All recipes run with root credentials (or credentials with sufficient policy permissions). These are admin operations, not actions the agent performs on itself.

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

Rules (mandatory)

1. Human confirmation before any policy change. Display the updated policy and explain what changes. Wait for explicit approval.
2. Before deleting an agent user, verify it is the intended non-root agent. Deleting users is permanent. If the target might be a root, admin, or human user — or you cannot confirm the target is the disposable provisioned agent — do not call delete_users; stop and ask the human to confirm the exact user.

Prerequisites

Requires root API credentials. All recipes run with root/admin access, not agent credentials.

TURNKEY_API_PUBLIC_KEY=    # Root API key — public component (hex)
TURNKEY_API_PRIVATE_KEY=   # Root API key — private component (P-256 hex)
TURNKEY_ORGANIZATION_ID=   # Turnkey organization UUID

Use the getting-started skill if you still need to verify credentials.

---

My agent's transaction was denied

Use get_policy_evaluations to see exactly which policy blocked it and why.

POST /public/v1/query/get_policy_evaluations

{
  "organizationId": "<ORG_ID>",
  "activityId": "<DENIED_ACTIVITY_ID>"
}

The response contains a policyEvaluations array. Each entry shows a policy and its outcome:

Outcome	Meaning
OUTCOME_ALLOW	This policy permitted the action
OUTCOME_DENY_EXPLICIT	This policy explicitly blocked the action (a DENY matched)
OUTCOME_DENY_IMPLICIT	No ALLOW policy matched — blocked by default deny
OUTCOME_REQUIRES_CONSENSUS	Policy requires multi-party approval before proceeding
OUTCOME_ERROR	Policy evaluation errored (likely a no-short-circuit issue — see managing-policies)