Docs menu

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.

Explain it

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:

API
POST /v1/agents/me/credential
Authorization: Bearer clik_…
JSON
{ "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):

API
POST /v1/projects/:id/keys/:keyId/credential
GET /v1/projects/:id/credentials

The 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:

  1. Ask for the message to sign:

    API
    GET /v1/agents/me/wallet/challenge?address=0x1234…abcd

    CLI returns a message like 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.000Z
  2. Sign the message exactly as given with the wallet (EIP-191 personal_sign).

  3. Send the address, the message and the signature:

    API
    POST /v1/agents/me/wallet
    JSON
    { "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:

JSON
{ "alg": "EdDSA", "typ": "agent-record+jwt", "kid": "q3N0b8xYcVdE2kLm" }

Its claims, decoded, for an agent with a bound wallet:

JSON
{
  "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 }
  }
}
ClaimMeaning
issThe CLI server that issued it
subThe wallet as did:pkh:eip155:1:<address> when one is bound; otherwise cli:agent:<keyId>
audWho it's for; only present when one was given
iat, nbf, expIssued, valid from (30 seconds before issue) and expiry, in Unix seconds
jtiThe credential's id, used to check and revoke it
cli.agentThe key's name, its id, the bound wallet (or null) and whether it's a hosted agent
cli.recordScore (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.establishedA long, clean record: at least 10 actions and a score of 80 or more
cli.operator.identityVerifiedWhether 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:

API
POST /v1/credentials/verify
JSON
{ "credential": "eyJhbGciOiJFZERTQSIs…", "audience": "https://their-service.example" }
JSON
{ "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:

TypeScript
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:

API
POST /v1/credentials/:jti/revoke

Project 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).