🪪 Persistent Agent Identity

Give agents a verifiable DID, ed25519 key pairs, peer attestations, and JWT-based auth tokens.

Register an Identity

POST /v1/identities
Authorization: Bearer <api_key>

{
  "display_name": "my-agent",
  "capabilities": ["search", "verify", "code"],
  "metadata": { "version": "1.0" }
}

→ {
  "identity": {
    "id": "550e8400-...",
    "did": "did:at:550e8400-...",
    "display_name": "my-agent",
    "capabilities": ["search", "verify", "code"],
    "metadata": { "version": "1.0" },
    "status": "active",
    "trust_score": 0,
    "created_at": "2026-03-17T04:00:00Z"
  },
  "private_key": "base64encodedprivatekey=="
}

⚠️ The private_key is returned only once. Store it securely — you'll need it to sign attestations and issue tokens.

Get / Update / Revoke

GET    /v1/identities/:id
PATCH  /v1/identities/:id   { "display_name": "new-name", "capabilities": [...] }
DELETE /v1/identities/:id

:id accepts either a UUID or a did:at:<uuid> string.

Key Management

// Add a new key (rotation)
POST /v1/identities/:id/keys
{ "label": "device-2" }

→ {
  "key": { "id": "key-uuid", "label": "device-2", "active": true, ... },
  "private_key": "newprivatekey=="
}

// List active keys
GET /v1/identities/:id/keys

// Revoke a key
DELETE /v1/identities/:id/keys/:kid

Attestations

Agents can attest to each other's trustworthiness. Each attestation is ed25519-signed and contributes to the subject's trust_score.

// Create a signed attestation
POST /v1/attestations
{
  "attester_id": "uuid-of-attester",
  "subject_id":  "uuid-of-subject",
  "claim":       "trustworthy",
  "private_key": "base64encodedprivatekey==",
  "evidence":    "Completed 50 tasks without errors",
  "weight":      1.0
}

→ {
  "attestation": {
    "id": "att-uuid",
    "attester_id": "...",
    "subject_id": "...",
    "claim": "trustworthy",
    "signature": "base64sig==",
    "weight": 1.0,
    "created_at": "..."
  },
  "subject_trust_score": 0.42
}

// Get a single attestation
GET /v1/attestations/:id

// List attestations received by an identity
GET /v1/identities/:id/attestations

// List attestations given by an identity
GET /v1/identities/:id/attestations/given

// Revoke an attestation
DELETE /v1/attestations/:id

Trust score is recomputed on every attestation write. Creator attestations carry 1.5× weight. Self-attestations have zero weight. Score clamps to [0, 1].

Discover Agents

GET /v1/discover?capability=verify&min_trust=0.5&q=data+agent&limit=20

→ {
  "identities": [
    { "id": "...", "did": "did:at:...", "display_name": "...",
      "capabilities": ["verify"], "trust_score": 0.74, ... },
    ...
  ]
}

Param	Description
capability	Filter by a single capability string
min_trust	Minimum trust score (0.0–1.0)
q	Freeform text search on name + metadata
limit	Max results (default 20)

Agent Tokens (JWT)

Issue short-lived ed25519-signed JWTs for agent-to-agent auth.

// Issue a token
POST /v1/identities/:id/tokens
{
  "private_key":  "base64encodedprivatekey==",
  "key_id":       "uuid-of-key-used-to-sign",
  "ttl_seconds":  3600,
  "audience":     "did:at:target-agent",
  "scope":        ["read", "write"]
}

→ {
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
  "expires_at": "2026-03-17T05:00:00Z"
}

// Verify a token
POST /v1/tokens/verify
{ "token": "eyJhbGci..." }

→ {
  "valid": true,
  "payload": { "sub": "did:at:...", "aud": "did:at:...", "exp": 1773724800, "scope": ["read","write"] }
}

Max TTL is 3600 seconds (1 hour). Tokens are verified against the issuer's public key fetched from the identity store.

SDK

// Python
pip install agenttool-sdk  # v0.3.0+

from agenttool import AgentTool
at = AgentTool()

result = at.identity.register("my-agent", capabilities=["search"])
identity, private_key = result["identity"], result["private_key"]

at.identity.attest(
    attester_id=identity["id"],
    subject_id=other_id,
    claim="trustworthy",
    private_key=private_key,
)

agents = at.identity.discover(capability="search", min_trust=0.5)
token  = at.identity.issue_token(identity["id"], private_key=private_key, key_id=key_id)

// TypeScript
npm install @agenttool/sdk  # v0.3.0+

import { AgentTool } from "@agenttool/sdk";
const at = new AgentTool();

const { identity, private_key } = await at.identity.register("my-agent", {
  capabilities: ["search"],
});

await at.identity.attest({
  attester_id: identity.id,
  subject_id: otherId,
  claim: "trustworthy",
  private_key,
});

const agents = await at.identity.discover({ capability: "search", min_trust: 0.5 });
const token  = await at.identity.issueToken(identity.id, { private_key, key_id });

Cross-Service Identity Linking

Pass identity_id when creating resources in other services to link them to a verified agent identity.

// Wallet tied to an identity
POST /v1/wallets
{ "name": "agent-wallet", "identity_id": "550e8400-..." }

// Memory stored under an identity
POST /v1/memories
{ "content": "...", "identity_id": "550e8400-..." }

// Trace linked to an identity
POST /v1/traces
{ "decision": {...}, "reasoning": {...}, "identity_id": "550e8400-..." }

Once linked, resources can be queried or filtered by identity_id across services.

Credits

Operation	Credits
Register identity	2
Create attestation	2
Issue token	1
Get / discover / verify token	1
Key add / revoke	1