Delegated Keys
A delegated key gives an agent its own signing authority on your Casper account — narrow enough that it can transact alone but can never change who holds the keys. Your master key grants it, your master key revokes it, and your master key never touches AgentOps servers.
HEADS UP
ag_ API key authenticates an agent to AgentOps. The delegated key is a Casper keypair that gives the agent authority on-chain. Different things, different lifecycles — see Credentials & Keys.The two halves
Delegation completes in two stages, and an agent is useful after the first one. The console shows which stage an agent is in, on its row in Agents.
- Half 1 — the key exists (off-chain). When you create an agent, AgentOps generates a dedicated Casper keypair for it inside the key vault. The private key is created in the vault and stays there; nothing exports it, and no operator ever sees it. Badge: Key granted (off-chain).
- Half 2 — the key has on-chain authority. You sign one deploy with your master wallet that adds the agent’s key as an associated key on your account. AgentOps verifies it landed, then promotes the key. Badge: On-chain ✓ (revocable).
A third state exists for agents created before a vault was configured: Custodial — the agent has no delegated key of its own and its actions are signed by the shared signer instead. Policy enforcement is identical; only the on-chain attribution differs.
Activating on-chain signing
On the agent’s row, click Activate on-chain signing. The dialog walks four steps:
- Connect your wallet via CSPR.click, using the master account that owns the funds.
- AgentOps returns an unsigned deploy — the grant arguments plus the session contract bytes. It signs nothing and asks for nothing secret.
- Your wallet signs and submits it. The master key never leaves your browser.
- AgentOps verifies the result on-chain and flips the key to granted.
If your connected wallet is not the account the grant targets, the dialog refuses rather than submitting a deploy that would silently do nothing.
What the grant deploy actually changes
The grant is asymmetric on purpose. It adds the agent’s key to your account and, in the same deploy, adjusts the thresholds:
| Setting | Value | Why |
|---|---|---|
| Agent key weight | 1 | Enough to send a deploy on its own |
| Master key weight | 3 | Master alone still satisfies key management |
| Deploy threshold | 1 | The agent can transact without you |
| Key-management threshold | 3 | The agent can never add or remove keys |
Read the bottom two rows together: weight 1 against a deploy threshold of 1 means the agent acts alone, while weight 1 against a key-management threshold of 3 means it can never grant itself more authority, add another key, or remove yours. The master bump to weight 3 is what keeps the account from being bricked — the master alone always clears key management, even if the agent key is unavailable.
How AgentOps signs after activation
At authorize time, once policy passes, the signer looks up the agent’s active delegated key and signs with it from the vault. If the agent has no delegated key, it falls back to the custodial signer. Either way the agent process never holds key material — it gets a decision, not a key.
The practical payoff of activation is attribution: on-chain, the deploy is signed by that agent’s key, so the chain itself records which agent acted, not just that your account did.
Revoking
There are two revocations, and they answer different questions.
Stop the agent now (proxy-side)
Revoke delegation suspends the agent, aborts its in-flight decisions that have not yet committed, and marks the delegated key revoked. It returns the aborted decision ids and the committed decision ids — check the committed list, because those were already signed and cannot be recalled. This is the fast path during an incident; use it first.
Remove the key from the chain (master-signed)
Revoke on-chain mirrors the grant: AgentOps returns an unsigned revoke deploy, your wallet signs it with the master key, and the agent’s key is removed entirely from the account — not set to weight 0. After it lands, the node rejects that key outright. Thresholds are left untouched.
NOTE
Rules worth knowing
- One active delegated key per agent. Enforced in the database — a grant cannot create a second active key.
- Your master key never reaches AgentOps. Every server call in this flow either returns unsigned data or verifies an on-chain result.
- Confirmation is verified, not trusted. A returned deploy hash is not proof. Promotion requires that the deploy executed and that the agent key is associated at weight 1. If the deploy has not finalized yet, the key stays pending and you retry.
- Activation is per network. The grant deploy is submitted on the network you are connected to. Activate on testnet to test; activate again on mainnet, with the mainnet master account, before running there.
- Delegation is not a policy bypass. A granted key still only gets used after the policy firewall says ALLOW.
The API behind the buttons
Everything above is available over HTTP with an operator (sk_) key, if you want to drive it from your own tooling:
GET /v1/agents/:id/delegation # has_key + grant_state
POST /v1/agents/:id/grant-delegated-key/init # → unsigned deploy args + wasm + chain name
POST /v1/agents/:id/grant-delegated-key/confirm # verifies on-chain, promotes to granted
POST /v1/agents/:id/revoke-delegated-key/init # → unsigned revoke deploy
POST /v1/agents/:id/revoke-delegated-key/confirm
POST /v1/agents/:id/revoke-delegation # proxy-side stop (SDK: revokeAgent)The signing step in the middle is deliberately not an API — it happens in your wallet. revokeAgent in the SDK maps to the last route.