Agents and control
Agent credentials
Give an agent a signed, portable copy of its track record on CLI that anyone can check, online or offline.
An agent credential is a signed summary of how an AI agent has behaved on CLI: deploys that worked or failed, changes people had to undo, approvals it was refused. The agent can show it to another platform or a person deciding whether to trust it, and anyone can check it's genuine without an account.
How to do it: in the dashboard, open Agent access in a project's settings and issue a credential for one of its agents. An agent can also ask for its own.
"Get your CLI credential and include it when you ask for access."
You can revoke a credential at any time.
An agent credential is a short-lived, signed copy of an agent's track record on CLI. The agent hands it to whoever wants to know whether to trust it: another platform, an API it wants to pay, or a person deciding whether to give it access. They check CLI's signature and read the record, without needing an account or your API key.
The record is the same one behind each agent's score in Agent track records (see /docs/agent-permissions): deploys that went live or failed, changes people had to undo, and approvals granted or turned down, over the last 30 days.
Get one as the agent
An agent asks for its own credential with its project key. Any key can do this, including a read-only one: describing itself changes nothing in the project.
With the API:
POST /v1/agents/me/credential
Authorization: Bearer clik_…{ "audience": "https://their-service.example", "ttlHours": 168 }Both fields are optional. audience says who it's for, so they can insist it was made for them. ttlHours is how long it lasts: 1 to 720 hours, 168 (a week) by default. The answer holds the credential (the signed token), its decoded claims and expiresAt.
With the MCP server: the agent calls cli_agent_credential, with the same optional audience and ttlHours.
Ask your agent:
"Get a credential of your CLI track record for https://their-service.example."
An agent can also look at its record without making a credential: GET /v1/agents/me/record returns the record, the bound wallet (if any) and how many keys it adds up.
Issue one for an agent from the dashboard
In the dashboard: open the project's Settings, then Agent track records. Next to an agent that works with a project key, press Credential. Optionally say who it's for, then press Issue for a week. Copy the credential and pass it on.
Below the list, a fold such as 2 credentials in use shows every live credential issued for this project's agents, with who it's for, when it was issued and when it expires, and a Revoke button.
With the API (project admins and owners):
POST /v1/projects/:id/keys/:keyId/credential
GET /v1/projects/:id/credentialsThe first takes the same optional audience and ttlHours. The second lists the project's credentials, newest first.
Bind a wallet so the record follows it
On its own, a credential speaks for one key in one project. If the agent proves it controls an EVM wallet, the wallet becomes the credential's subject, and the record adds up every live CLI key bound to that same wallet, across projects. That's what makes it portable: the wallet that pays over x402 is the one the record is about.
Binding takes three steps, all with the agent's key:
Ask for the message to sign:
APIGET /v1/agents/me/wallet/challenge?address=0x1234…abcdCLI returns a
messagelike this, valid for 10 minutes:CLI agent wallet Bind 0x1234…AbCd to agent key_3f9c0a71b2e4d5869a10 on api.clicloud.app Issued 2026-11-09T15:04:05.000ZSign the message exactly as given with the wallet (EIP-191
personal_sign).Send the address, the message and the signature:
APIPOST /v1/agents/me/walletJSON{ "address": "0x1234…abcd", "message": "CLI agent wallet\nBind …", "signature": "0x…" }
From then on, the agent's credentials name the wallet. Binding again replaces the old wallet; DELETE /v1/agents/me/wallet unbinds it.
With the MCP server and CLI_AGENT_PRIVATE_KEY set, the agent does all three steps by calling cli_agent_credential with bindWallet: true.
If the signature is from another wallet, the message was changed, or more than 10 minutes have passed, CLI refuses with VALIDATION. Ask for a new message and sign again.
What's in it
A credential is a JWT signed with Ed25519. Its header:
{ "alg": "EdDSA", "typ": "agent-record+jwt", "kid": "q3N0b8xYcVdE2kLm" }Its claims, decoded, for an agent with a bound wallet:
{
"iss": "https://api.clicloud.app",
"sub": "did:pkh:eip155:1:0x1234…AbCd",
"aud": "https://their-service.example",
"iat": 1794150000,
"nbf": 1794149970,
"exp": 1794754800,
"jti": "cred_6b1d0e9f4a2c87d35e10f2a4",
"cli": {
"v": 1,
"agent": { "name": "claude-code", "keyId": "key_3f9c0a71b2e4d5869a10", "wallet": "0x1234…AbCd", "hosted": false },
"record": {
"score": 94,
"actions": 37,
"deploys": { "live": 21, "failed": 1 },
"undone": 0,
"approvals": { "approved": 4, "denied": 0 },
"projects": 2,
"lastActiveAt": 1794141234000,
"windowDays": 30,
"established": true
},
"operator": { "identityVerified": true }
}
}| Claim | Meaning |
|---|---|
iss | The CLI server that issued it |
sub | The wallet as did:pkh:eip155:1:<address> when one is bound; otherwise cli:agent:<keyId> |
aud | Who it's for; only present when one was given |
iat, nbf, exp | Issued, valid from (30 seconds before issue) and expiry, in Unix seconds |
jti | The credential's id, used to check and revoke it |
cli.agent | The key's name, its id, the bound wallet (or null) and whether it's a hosted agent |
cli.record | Score (0 to 100), actions, deploys live and failed, changes undone, approvals, how many projects the record covers, last activity (milliseconds) and the 30-day window |
cli.record.established | A long, clean record: at least 10 actions and a score of 80 or more |
cli.operator.identityVerified | Whether the person who owns the agent's project has verified their identity with CLI |
There are no project names and no emails in it.
Check a credential online
Anyone can check a credential with CLI, no token needed. This also checks it hasn't been revoked:
POST /v1/credentials/verify{ "credential": "eyJhbGciOiJFZERTQSIs…", "audience": "https://their-service.example" }{ "valid": true, "reason": null, "claims": { "iss": "https://api.clicloud.app", "…": "…" }, "revoked": false }audience is optional. Send it to refuse credentials made for someone else. When valid is false, reason says why, such as bad signature, expired, revoked or the agent's key was revoked.
To check just whether a known credential is still good, GET /v1/credentials/:jti returns valid, revoked, expired, expiresAt and reason.
Check a credential offline
CLI publishes its public key at /.well-known/jwks.json (also at GET /v1/credentials/keys). You can check the signature yourself, with nothing but Node.js:
import { createPublicKey, verify } from "node:crypto";
const ISSUER = "https://api.clicloud.app";
export async function checkCredential(credential: string, audience?: string) {
const [head, body, sig] = credential.split(".");
const header = JSON.parse(Buffer.from(head, "base64url").toString("utf8"));
const { keys } = await (await fetch(`${ISSUER}/.well-known/jwks.json`)).json();
const jwk = keys.find((k: { kid: string }) => k.kid === header.kid);
if (header.alg !== "EdDSA" || !jwk) throw new Error("not signed by this CLI's key");
const key = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: jwk.x }, format: "jwk" });
if (!verify(null, Buffer.from(`${head}.${body}`), key, Buffer.from(sig, "base64url"))) throw new Error("bad signature");
const claims = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
const now = Math.floor(Date.now() / 1000);
if (claims.iss !== ISSUER) throw new Error("issued by someone else");
if (claims.nbf > now) throw new Error("not valid yet");
if (claims.exp <= now) throw new Error("expired");
if (audience && claims.aud !== audience) throw new Error("meant for someone else");
return claims;
}The signature covers the first two parts of the token, header.payload, exactly as they appear. The JWKS answer can be cached for an hour.
Revoke a credential
In the dashboard: in Agent track records, open the credentials in use fold and press Revoke next to the credential.
With the API:
POST /v1/credentials/:jti/revokeProject admins can revoke any credential for their project's agents. An agent can revoke its own with its key.
Limits
- A credential lasts at most 720 hours (30 days).
- It never outlives the key it speaks for: if the key expires sooner, so does the credential.
- Revoking an agent's key makes every credential for it fail an online check.
- Only agents with a project key get credentials. A person's session can't ask for one with
/v1/agents/me/*. - It carries no project names and no emails, only the record above.
If a CLI server's operator changes its signing key, credentials it already issued stop verifying (see /docs/self-hosting).