Agent identity

Bring your own agent identity, or use an agent passport

APS needs to know which key an agent signs with. It works with an identifier you already use, and it can create a passport for an agent that has none.

Bring your own identity

The delegation record names its issuer and its subject as identifier strings, and the verifier gets the keys through a resolver that you supply. The record format does not limit which identifier scheme you use.

SDK 8.0.1 ships helpers for did:key and did:web. It also has helpers that carry a SPIFFE identity or an OAuth token into APS after you verified it yourself. Those helpers map fields and check no signature.

Or use an agent passport

An agent passport is a signed record that identifies an agent by its public key. The SDK can create one for an agent that has no identity yet, and an issuer can countersign it.

Anyone who has the record and the public key can check the signature. A valid signature shows that the holder of the private key signed the record and that the record was not changed. It does not show who owns the agent or what the agent may do.

Identity is the first of three questions

Which agent is this?

An identifier and its key answer this. You can use an identifier you already have or create an agent passport that contains the public key of the agent.

Who does it act for?

A principal binding names the person or organization that authorizes the agent. The verifier decides whether it trusts the signer of that binding.

What may it do?

A delegation gives the agent specific authority, for example to read a document, use a tool or spend within a limit. An agent can pass authority to another agent, and the new delegation cannot grant more than the one before it.

A valid signature is not permission

A passport can carry a valid signature while no trusted principal binding and no active delegation exist for it. The protocol defines a separate check for each of these records. A gateway can then use the checked authority to decide whether an action may go ahead.

What the published SDK covers

SDK 8.0.1 exports the passport functions createPassport, verifyPassport and countersignPassport. The newer PassportV2 and PrincipalBindingV1 records of draft -04 are implemented in the SDK source, and the published package does not export them. The identity reference lists what 8.0.1 exports for each identifier scheme.

Start with a working example

The quickstart builds one governed action on your machine with a signed grant, a revocation and receipts, and its test asserts every outcome.

Run the quickstart Read the identity reference Read the delegation reference

Other SDK modules

The SDK includes optional APIs for coordination, commerce, reputation and governance. Some exports are experimental, and some throw a migration error when called. Check the API reference before you use one. The status page explains the maturity labels.

Four examples from the older module tour

The SDK source at commit 1284887 exports every function these examples import. They are fragments and were not run for this page.

Coordination Primitives

import { createTaskBrief, submitEvidence, reviewEvidence } from 'agent-passport-system';

const brief = createTaskBrief({
  title: 'Competitive Protocol Analysis',
  roles: { researcher: { count: 1 }, analyst: { count: 1 } },
  deliverables: [{ id: 'd1', description: 'Evidence packet', assignedRole: 'researcher' }],
  acceptanceCriteria: [{ id: 'c1', description: 'Min 3 sources', threshold: 70 }]
}, operatorKeys);

// Full lifecycle: brief → assign → accept → evidence → review → handoff → deliverable → complete

Cross-Chain Data Flow Authorization

import { createTaintLabel, mergeTaints, checkDataFlow,
  createCrossChainPermit, countersignPermit } from 'agent-passport-system';

// Agent reads Alice's file → tainted with Alice's context
const taint = createTaintLabel('alice', 'chain-a', 'del-001');

// Agent tries to send via Bob's email scope → BLOCKED
const result = checkDataFlow({
  inputTaint: mergeTaints(taint),
  actionPrincipalId: 'bob',
  actionScope: 'email:send',
  permits: []
});
// → { verdict: 'blocked', reason: 'No valid CrossChainPermit found.' }

E2E Encrypted Messaging

import { createEncryptedAgoraMessage, decryptAgoraMessage } from 'agent-passport-system'

const msg = await createEncryptedAgoraMessage({
  subject: 'Confidential report',
  content: 'Q4 numbers look strong.',
  senderAgentId: 'analyst-001',
  recipientAgentId: 'cfo-agent',
  // ... keys, topic, delegationId, sequenceNumber
})
// msg.message.ciphertext → encrypted
// msg.outerSignature → verifiable without decrypting

const result = await decryptAgoraMessage(msg, recipientPrivateKey, 'cfo-agent')
// result.payload.content → 'Q4 numbers look strong.'
// result.valid → true (both signatures verified, recipient matches)

Obligations Model

import { createObligation, resolveObligation } from 'agent-passport-system'

const obligation = createObligation({
  delegationId: 'del-001',
  action: { type: 'report:generate', scope: 'reporting:weekly', description: 'Weekly status report' },
  deadline: '2026-03-24T17:00:00Z',
  evidence: { type: 'action_receipt', matchCriteria: { toolMatch: 'report:generate' } },
  penalty: { type: 'escalate_to_principal', severity: 'minor', gracePeriodMinutes: 30, autoExecute: false },
  // ... agent keys, principal keys
})

// After deadline: gateway resolves
const resolution = resolveObligation({ obligation, receipts: [...], gatewayId, gatewayPrivateKey })
// resolution.outcome → 'fulfilled' | 'unfulfilled_no_evidence' | 'unfulfilled_tool_failure' | 'terminated_by_revocation'