KYA Platform Documentation

Why Choose KYA Platform?

S

Self-Instantiation

Rules for sub-agent spawning by an already-registered orchestrator. This is not the primary agent's own onboarding — primary agents always need human-in-the-loop or crypto-keypair step-up to register (seeAgent Access). Self-instantiation governs whether a registered agent can mint downstream workers inside its own PDLSS envelope.

{
  allowed: true,
  maxSubAgents: 3,
  maxDepth: 2,
  inheritPermissions: true,
  requireApproval: true
}

Worked register call (SDK)

The complete payload using @astrasyncai/verification-gateway:

import { AstraSync } from '@astrasyncai/verification-gateway/registration';

const client = new AstraSync({ apiKey: process.env.ASTRASYNC_API_KEY });

await client.register({
  name: 'My Shopping Agent',
  agentType: 'shopping_assistant',
  apiEndpoint: 'https://my-agent.example.com/astrasync',

  model: { modelName: 'claude-opus-4-7', modelProvider: 'anthropic', modelType: 'llm' },
  framework: { frameworkName: 'langchain', frameworkVersion: '0.3.0' },

  // First-class as of v1.0.0 (was previously stuffed in metadata.protocols[]).
  protocols: ['acp', 'ap2', 'a2a', 'vi', 'mpp', 'ucp'],

  pdlss: {
    purpose: { categories: ['shopping'], allowedActions: ['search', 'compare', 'purchase'] },
    duration: { maxSessionDuration: 3600 },
    limits: { autonomousThreshold: 50, approvalThreshold: 500, currency: 'AUD' },
    scope: { jurisdictions: ['AU', 'NZ'] },
  },
});

Trust score: dynamic and intentionally opaque

trustScore is recomputed at runtime on every request from the agent's metadata, certifications, observed behaviour, and policy state — the value at register-time is a baseline only.

The exact algorithm is intentionally opaque (anti-gaming).Score improves with metadata completeness — populatingmodel,framework, and certifications is the most reliable lever you have.

Why agents can't read their own permissions

GET /api/agents/{id}returns 403 when the caller is the agent itself. This is by design: permissions live in your agent's context window from registration onward. If an agent has to ask "what can I do?" at runtime, that itself is a drift signal — natural forgetting, prompt injection, or hijack.

The owner can read permissions via the dashboard or via API key auth at any time. The agent's own bearer token cannot.

Step-up rules at registration

The 3-step verification handshake

1. Owner sets agent's PDLSS at registration. Immutable thereafter. This is the agent's declared envelope.
2. Merchant sets endpoint access policy at endpoint registration. Independent of any single agent — describes what the endpoint will accept from anyone.
3. Per session:agent declares intended PDLSS for this call → merchant checks against endpoint policy → AstraSync confirms the agent is operating within its registered boundaries → approve + record. If outside endpoint policy: merchant denies + records. If within endpoint policy but outside the agent's registered boundaries: AstraSync tells merchant to deny + records.

Both agent and merchant have purposes; session intent must overlap with both envelopes for access to be granted.

Async outreach: register on someone else's behalf

When the owner doesn't yet have an account:

POST /api/agents/request-registration
{
  "agentName": "Their agent",
  "ownerEmail": "[email protected]",
  "agentDescription": "...",
  "reason": "..."
}

→ 202 { "requestId": "uuid", "message": "..." }

We email the owner. If they already have an account, the email links straight to a sign-in page that lands on the pending-approval queue. Otherwise it walks them through account + KYD + agent registration. Poll status:

GET /api/agents/request-registration/{requestId}

→ 200 {
  "status": "pending" | "approved" | "denied" | "expired",
  "agentId": "uuid | null",
  "requestedAt": "...",
  "lastEventAt": "..."
}

Common fields (both branches)

{
  "success": true,
  "access": {
    "allowed": boolean,
    "accessLevel": "none" | "restricted" | "read-only" | "standard" | "full",
    "reason": string
  },
  "recommendation": "grant" | "deny" | "step_up_required" | "audit",
  "recommendationReasons": string[],
  "advisory"?: {                  // present on anonymous responses
    "ial": "unverified",
    "registrationUrl": string,
    "docsUrl": string,
    "policy": "deny" | "audit" | "allow_partial" | "allow_full",
    "restrictionsExplained": string[]
  },
  "warningHeader"?: {             // present when policy = 'audit'
    "name": "X-Astra-Unverified-Warning",
    "value": string
  }
}

access.accessLevel is the band the SDK enforces routes against. v2.3.9 renamed guidance → restricted to remove the value-name collision with the guidance: {} response object that never existed (denial branches return none).

recommendation is the four-bucket activity-feed bucket the event is counted under. audit (v2.3.8+) is a soft-launch grant that allows the call but stamps an X-Astra-Unverified-Warningheader on the merchant's response — distinct from grant (verified) and deny.

Verified-agent branch — request body included agentId

{
  "success": true,
  "access": { "allowed": true, "accessLevel": "standard", "reason": "..." },
  "recommendation": "grant",
  "recommendationReasons": ["..."],
  "agent": {
    "astraId": "ASTRA-...",
    "name": string,
    "trustScore": number,
    "agentStatus": "active",
    "blockchainStatus": "verified",
    "runtimeChallengeSupported": boolean
  },
  "sessionId": "uuid",            // ← key field (see below)
  "tokenGuidance"?: { ... },      // present when SDK opted in
  "runtimeChallenge"?: { ... }    // present when challenge was issued
}

sessionId is the verified-traffic correlation key. The SDK uses it to report local overrides (e.g. an MCP toolGate floor exceeds the granted band) via POST /api/agents/verify-access/{sessionId}/decision with overriddenBy + requestedLevel + grantedLevel so the activity feed shows a verification.local_override event paired with the original grant.

Anonymous branch — no agentId in request body

Triggered when the calling agent is not registered (or the SDK chose not to send an ASTRA-id). The endpoint's unverifiedAgentPolicy resolves the response. All four policy values produce the same wire shape but populate access, recommendation, and advisory.policy differently.

{
  "success": true,
  "access": { "allowed": boolean, "accessLevel": "...", "reason": "..." },
  "correlationId": "uuid",        // ← key field, anonymous-only (see below)
  "advisory": {
    "ial": "unverified",
    "registrationUrl": "https://astrasync.ai/register",
    "docsUrl": "https://astrasync.ai/docs/agent-access",
    "policy": "deny" | "audit" | "allow_partial" | "allow_full",
    "restrictionsExplained": ["..."]
  },
  "warningHeader"?: { ... },      // only when policy = 'audit'
  "agent"?: { ... },              // only when caller fingerprint matched a known platform
  "recommendation": "grant" | "deny" | "step_up_required" | "audit",
  "recommendationReasons": ["..."]
}

correlationId (v2.3.10+) is the anonymous-traffic linkage key. The backend mints a fresh correlationIdper anonymous request, persists it on the emitted event, and surfaces it on the response. SDK >= 2.3.10 reads it onto EnhancedVerificationResult.correlationId and posts to POST /api/agents/verify-access/local-overrideto record any SDK-side override of the server's grant. correlationId plays the same event-pairing role on the anonymous branch that sessionId plays on the verified branch — they are mutually exclusive by design, not transitional.

Sessionless local-override report — POST /agents/verify-access/local-override

The SDK calls this when it locally denies a call the server granted (e.g. MCP toolGates floor exceeds access.accessLevel) AND there's no sessionId available (anonymous traffic). Rate-limited to 30/minute/IP.

POST /api/agents/verify-access/local-override
Content-Type: application/json

{
  "correlationId": "uuid",        // from the original verify-access response
  "overriddenBy": "toolGate" | "methodGate" | "trustScore" | "other",
  "toolName"?: "start_checkout",
  "requestedLevel": "standard",   // what the local floor required
  "grantedLevel": "restricted",   // what the server granted
  "reason"?: "toolGate floor exceeded"
}

# 200 → emits verification.local_override event linked to the original
#       event by correlationId. counterpartyId / counterpartyOwnerId
#       are inherited from the original event so the activity feed
#       attributes the override correctly.
# 404 → correlationId did not match any anonymous verify-access event
# 400 → malformed payload (Zod rejection)
# 429 → rate limit exceeded

Activity-feed event types you'll see

Click any row in /activity > Recent Activity to expand the full eventData payload — useful for verifying paired-event linkage (a verification.local_override row should share its correlationId with an earlier verification.unverified_* row).

Counterparty-Side: Verifying Incoming Agents

Mount Express middleware to verify agents hitting your API. The middleware calls AstraSync's verify-access endpoint and populates req.agentVerification with the result.

import { createMiddleware } from '@astrasyncai/verification-gateway/express';

// v2.3.7+ — per-route policy lives in the AstraSync dashboard.
// The SDK fetches it on init via counterpartyId; do NOT pass routes here.
app.use(createMiddleware({
  apiBaseUrl: 'https://astrasync.ai/api',     // always includes /api
  apiKey: process.env.ASTRASYNC_API_KEY,
  counterpartyId: 'ASTRAE-...',       // your endpoint id from the dashboard
  setPassThroughHeader: true,         // recommended for staging — surfaces
                                       // pass-through mode when no policy
                                       // is configured (see /docs#endpoints)
}));

After middleware runs, req.agentVerification contains (v2.3.0+):

• →.verified — whether the agent passed verification
• →.accessLevel — server-decided level (none, restricted, read-only, standard, full, internal). The SDK reads this verbatim from the verify-access response — no client-side trust-score remap (v2.3.0+ contract). v2.3.9 (defect #30): renamed guidance band → restricted. See the trust-score tier cheatsheet below for the canonical mapping.
• →.agent — astraId, name, trustScore, agentStatus (was status), blockchainStatus (new: verified | pending | failed | unverified)
• →.advisory — present on anonymous calls (v2.3.0+). {ial, registrationUrl, docsUrl, policy, restrictionsExplained} tells the agent how to upgrade based on the endpoint's unverifiedAgentPolicy.
• →.pdlss — full permission boundaries
• →.tokenGuidance — recommended scopes, TTL, rate limits
• →.recommendation — grant, deny, or step_up_required

Configure attribution + init self-test (v2.3.0+)

createMiddleware({
  apiBaseUrl: 'https://astrasync.ai/api', // always include /api
  counterpartyId: 'ASTRAE-xxxxx',         // your endpoint's ASTRAE-id from registration
  counterpartyUrl: 'https://merchant.example',
  // disableInitChecks: true               // skip the HEAD probe in tests
});

counterpartyId tells the server to attribute traffic by ASTRAE-id rather than resolving by URL — useful when the same merchant runs multiple endpoints under one origin (e.g. /checkout + /mcp with separate policies).

On first verify() call the SDK fires a HEAD probe to ${apiBaseUrl}/agents/verify-access and warns once if the response content-type is text/html — catches the case where apiBaseUrl is pointing at a marketing 404.

Enhanced Verification with Sessions

import { verify } from '@astrasyncai/verification-gateway';

const result = await verify(config, {
  credentials: { astraId: 'ASTRA-xxxxx' },
  purpose: 'financial_transaction',
  createSession: true,
  enableRuntimeChallenge: true,
});
// result.sessionId, result.runtimeChallenge, result.tokenGuidance

Recording a Decision

import { recordDecision } from '@astrasyncai/verification-gateway';

await recordDecision(config, {
  sessionId: result.sessionId,
  decision: 'granted',
  reason: 'Agent meets all requirements',
  tokenIssued: true,
});

Agent-Side: Presenting Credentials

Use AgentClient to automatically inject AstraSync credentials into outgoing requests across all supported protocols.

import { AgentClient } from '@astrasyncai/verification-gateway';

const client = new AgentClient({
  agentId: 'ASTRA-xxxxx',
  challengeUrl: 'https://my-agent.com/astrasync/challenge',
  pdlss: {
    purpose: { category: 'read_data' },
    duration: { maxSessionDuration: 3600 },
    scope: { jurisdiction: 'US' },
  },
});

// HTTP — headers auto-injected
const response = await client.fetch('https://counterparty.com/api/data');

// A2A — metadata.astrasync block auto-added
const task = client.prepareA2AMetadata({ id: 'task-1' });

// MCP — _meta.astrasync block auto-added
const params = client.prepareMcpMeta({ tool: 'search', query: '...' });

X-Astra-* Headers (HTTP Transport)

Three verification tiers

1. Direct registration

POST /api/endpoints
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "counterpartyType": "api",
  "name": "Invoice API",
  "endpointUrl": "https://api.example.com",
  "trustScoreRequirement": 20
}

# → returns astraeId "ASTRAE-<22-char>"

2. Claim from the Discovered tab

Every authenticated verify-access call with a counterpartyUrlthat doesn't match a registered row creates a discovered row owned by the caller (the SDK operator). These appear in the Discovered tab at /endpoints — click Claim to promote them to self_asserted without losing traffic history.

Removing auto-registered endpoints from your active list

Auto-registered endpoints carry an auto-registered badge on the endpoints list. To remove one from your active list, use the standard Deactivateaction — the same flow you'd use for endpoints you registered yourself. There's no separate “Dismiss” action: deactivate is the dismiss path for auto-registered rows.

Deactivated rows remain available under the Deactivated tab so audit history stays intact. Use Archive from there if you want the row out of the default views permanently — the underlying audit events are not deleted, just hidden from the working list.

Where orphans live (management vs activity views): auto-registered or discovered orphan endpoints attributed to your account appear in /activity → Endpoints for traffic-attribution and audit purposes. The /endpointsmanagement view filters to endpoints you've explicitly claimed — that's deliberate so the working list stays focused on owned configuration. To deactivate or archive an orphan, find it under /activity → Endpoints, click through to its detail, and use the Deactivate action — same flow as for claimed endpoints.

Agent-side (outbound)

/activity → Agents tab. Each agent row shows a categorisation badge cluster:

• Internal — endpoint owned by your account.
• External — endpoint owned by another AstraSync account. Privacy-masked: only ASTRAE-id and type surface.
• Unregistered — URL not claimed by any account.

Endpoint-side (inbound)

/activity → Endpoints tab. Expand any registered endpoint to see callers categorised:

• Internally governed — the calling agent is owned by your account.
• Externally governed — different AstraSync owner. ASTRA-id only; all other fields masked.
• Ungoverned — no AstraSync record. Source IP, User-Agent, Host, Referer, and Agent Card URL (when present) surface for forensics.

API key

Authorization: Bearer kya_<api-key>

SDK config: new ExpressMiddleware({ apiKey: process.env.ASTRASYNC_KEY, ... }). The Express and Next.js adapters auto-wire this.

Step 1: Create Your Policy

All Local Guard adapters share the same PDLSS policy file. Create it once, then choose which adapter to run for your platform.

npm install @astrasyncai/verification-gateway

# Interactive wizard — creates local-policy.yaml
npx astrasync guard setup

The wizard asks plain-language questions about what your agent should be allowed to do and generates a local-policy.yaml file using the same PDLSS schema as the cloud — so upgrading later requires zero migration.

The same verification gateway SDK that agents use is what counterparties use to interpret the declarations. One verify-access call returns:

• Declared protocols as an array — you can route an ACP request differently from a UCP request without negotiating capabilities up front.
• PDLSS boundariesalready merged from every declared protocol — you see the maximum transaction value the agent is authorised for, the jurisdictions it's scoped to, the counterparties it's allowed to transact with.
• Runtime trust signals like runtimeChallengeSupported (whether the agent has a verification endpoint mounted), trust score, and KYD status — useful for tier-based acceptance policies.
• Recommendation — grant, step_up_required, or deny — and the reasons, so you can either trust the recommendation or apply your own logic on top.

import { CounterpartyClient } from '@astrasyncai/verification-gateway';

const client = new CounterpartyClient({ apiKey: process.env.ASTRASYNC_KEY });
const result = await client.verifyAccess({
  agentId: req.headers['x-astrasync-agent-id'],
  purpose: 'financial_transaction',
  transactionValue: 250,
  currency: 'USD',
});

// result.agent.protocols           → ['a2a', 'acp', 'mpp']
// result.agent.runtimeChallengeSupported → true
// result.pdlss.limits.approvalThreshold  → 500
// result.recommendation             → 'grant'

A2A — Agent2Agent Protocol (Linux Foundation, v1.0 GA)

Google & Linux Foundation's open standard for how agents talk to other agents. Defines an agent card schema (name, skills, transports, security) and the JSONRPC / gRPC / HTTP+JSON transport options. Most agents declare A2A as a baseline communication protocol and layer commerce protocols on top.

You declare: agent URL, version, skills (≥1), transport, optional provider info and security schemes. What you get: the verification gateway endpoint pre-fills the agent URL automatically when both target the same server.

ACP — Agentic Commerce Protocol

OpenAI & Stripe's commerce checkout protocol. A merchant exposes a product feed, a checkout endpoint, and a webhook URL; agents discover the products and trigger Stripe-backed checkout sessions on the merchant's behalf.

You declare: merchant ID, checkout endpoint, product feed URL, webhook URL, supported payment methods (card / Apple Pay / Google Pay / Stripe Link / bank transfer), fulfillment options. PDLSS pre-fill: purpose financial_transaction, checkout domain + merchant:<id> added to counterparties.

{
  "protocols": ["a2a", "acp"],
  "acp": {
    "merchantId": "merchant_abc123",
    "checkoutEndpoint": "https://api.shop.com/checkout",
    "productFeedUrl": "https://api.shop.com/feed",
    "webhookUrl": "https://api.shop.com/webhooks/orders",
    "supportedPaymentMethods": ["card", "apple_pay"],
    "fulfillmentOptions": ["shipping", "digital_delivery"]
  }
}

AP2 — Agent Payments Protocol

Google's decentralised payment authorisation protocol. Identity is via DID (Decentralised Identifier); authority is granted through mandates (intent / cart / payment) signed by a human supervisor. Agents declare the maximum transaction value they're authorised for, allowed currencies and regions, and whether human delegation is enabled.

You declare: agent DID, max transaction value, allowed currencies, allowed regions, mandate types, delegation flag. PDLSS pre-fill: max transaction value flows to both autonomous and hard limits (the protocol-authorised amount IS the autonomous ceiling); allowed regions to jurisdictions; currency from the first allowed currency; delegation enables self-instantiation.

{
  "protocols": ["a2a", "ap2"],
  "ap2": {
    "agentDid": "did:web:agent.example.com",
    "policyClaims": {
      "maxTransactionValue": 500,
      "allowedCurrencies": ["USD"],
      "allowedRegions": ["US", "GB"]
    },
    "delegationEnabled": true,
    "mandateTypes": ["intent", "cart"]
  }
}

UCP — Universal Commerce Protocol

Google & Shopify's capability-based commerce protocol. The agent points at a UCP manifest (/.well-known/ucp) listing the capabilities it supports (checkout, discount, fulfillment, identity linking, order management, token exchange) and the transports it speaks (A2A, MCP, REST, embedded).

You declare: manifest URL, version, capabilities, transports, custom extensions. PDLSS pre-fill: checkout / payment capabilities add financial_transaction purpose; fulfillment adds execute_action; manifest domain added to counterparties.

{
  "protocols": ["a2a", "ucp"],
  "ucp": {
    "manifestUrl": "https://shop.example.com/.well-known/ucp",
    "version": "1.0",
    "capabilities": [
      "dev.ucp.shopping.checkout",
      "dev.ucp.shopping.fulfillment"
    ],
    "transports": ["a2a", "rest"]
  }
}

MPP — Machine Payments Protocol

Stripe's machine-to-machine payment protocol over HTTP 402. The agent declares its accepted payment rails (card via Stripe / Visa SPTs, stablecoins via Tempo, Lightning), the spending limit it's authorised for, and the facilitator endpoint it talks to.

You declare: merchant ID, facilitator URL, payment methods, currency, spending limit. PDLSS pre-fill: spending limit flows to autonomous and hard limits; facilitator domain + merchant:<id> added to counterparties; currency mirrored to PDLSS.

{
  "protocols": ["a2a", "mpp"],
  "mpp": {
    "merchantId": "merchant_abc123",
    "facilitatorUrl": "https://mpp.example.com",
    "paymentMethods": ["card", "stablecoin"],
    "currency": "USD",
    "spendingLimit": 500
  }
}

x402 — HTTP 402 on-chain payments

Coinbase's HTTP 402 payment protocol for paying for web resources with on-chain stablecoins. Servers return 402 with payment requirements; the agent pays via a facilitator and retries with proof. Agents declare wallet, supported chains (Base, Polygon, Solana), supported tokens (USDC default), and the facilitator URL.

You declare: wallet address, supported chains, supported tokens, facilitator URL, spending limit. PDLSS pre-fill: spending limit flows to autonomous and hard limits; facilitator domain to counterparties; currency defaults to USDC if it appears in the supported-token list.

{
  "protocols": ["a2a", "x402"],
  "x402": {
    "walletAddress": "0x1234...",
    "supportedChains": ["base", "polygon"],
    "supportedTokens": ["USDC", "USDT"],
    "facilitatorUrl": "https://pay.coinbase.com",
    "spendingLimit": 100
  }
}

VI — Verifiable Intent

Mastercard & Google's 3-layer SD-JWT credential chain proving human authorisation for commerce transactions. Two modes: Immediate (user confirms each action, 2-layer chain) and Autonomous (agent delegated, 3-layer chain with constraint enforcement). VI's 8 constraint types (merchant allowlists, payment amounts, budgets, recurrence, line items) map directly to PDLSS boundaries.

You declare: execution mode, agent public key (JWK/PEM), key ID, credential provider, supported mandate types, payment amount constraints, budget limits. PDLSS pre-fill: Autonomous/Both mode enables self-instantiation; payment amount max flows to autonomous and hard limits; allowed merchants become counterparties; currency mirrored.

{
  "protocols": ["a2a", "vi", "agentpay"],
  "vi": {
    "executionMode": "Autonomous",
    "kid": "key-1",
    "supportedMandateTypes": ["checkout", "payment"],
    "defaultConstraints": {
      "paymentAmount": { "currency": "USD", "max": 10000 }
    }
  }
}

Agent Pay — Mastercard

Mastercard's payment execution protocol using RFC 9421 HTTP Message Signatures. Agents sign every request (browse and purchase tags) using ECDSA P-256 or RSA-PSS; the Mastercard Agent Registry holds the public key for verification. Agent Pay handles the payment rail; VI handles the authorisation chain — they are complementary.

You declare:agent public key, Mastercard Agent ID, signature algorithm, allowed merchant domains, DTVC formats, consumer ID&V method, token binding scope. PDLSS pre-fill: allowed merchant domains become counterparties; always financial_transaction purpose.

{
  "protocols": ["a2a", "vi", "agentpay"],
  "agentpay": {
    "mastercardAgentId": "mc-agent-12345",
    "signatureAlgorithm": "ecdsa-p256-sha256",
    "allowedMerchantDomains": ["store.example.com"],
    "tokenBindingScope": "per-transaction"
  }
}

TAP — Visa Trusted Agent Protocol

Visa's equivalent of Agent Pay, also using RFC 9421 HTTP Message Signatures. ~85% of the infrastructure is shared with Agent Pay — the only differences are the registry endpoint (Visa's JWKS at mcp.visa.com/.well-known/jwks) and the payment credential format (Intelligent Commerce tokens vs Agentic Tokens).

You declare: agent public key, Visa Agent ID, signature algorithm, allowed merchant domains, token type (agent-specific or PAR), passkey enrollment. PDLSS pre-fill: allowed merchant domains become counterparties.

{
  "protocols": ["a2a", "tap"],
  "tap": {
    "visaAgentId": "visa-agent-12345",
    "signatureAlgorithm": "rsa-pss-sha512",
    "allowedMerchantDomains": ["shop.example.com"],
    "tokenType": "agent-specific-token",
    "passkeyEnrolled": true
  }
}

Agents may arrive with existing credentials from external providers — a Mastercard L1 credential via VI, a DID from an AP2 Credential Provider, or a Visa agent token. AstraSync assigns an ASTRA-ID as the primary identity anchor but accepts and stores third-party credentials alongside it.

Supported formats: DID (Decentralized Identifier), Verifiable Credential (VC), SD-JWT, X.509 certificate. When an agent presents a third-party credential at runtime, the gateway resolves it to the ASTRA-ID and proceeds with normal verification.

Third-party credentials appear as an optional section in the registration form when any Payment Network protocol (VI, Agent Pay, TAP) is selected.