Portable Credentials

Portable Credentials are signed JWT tokens that encode an agent's trust scores, allowing any third party to verify an agent's reputation without calling the VeriSwarm API in real time.

What Are Portable Credentials

A Portable Credential is an ES256-signed JSON Web Token (JWT) issued by VeriSwarm that captures a point-in-time snapshot of an agent's trust profile. The token contains identity scores, risk assessments, policy tier, verification status, and a composite trust score. Because the token is cryptographically signed, any party with access to VeriSwarm's public key can verify its authenticity offline.

Portable Credentials solve a fundamental problem in multi-agent systems: how does Agent B know that Agent A is trustworthy, without requiring a synchronous API call to a central authority? The answer is that Agent A carries a signed credential that Agent B can verify locally.

How They Work

The credential lifecycle follows four steps:

  1. Request -- An agent authenticates with its agent API key and requests a credential from POST /v1/credentials/issue.
  2. Sign -- VeriSwarm loads the agent's latest score snapshot, builds a JWT payload, and signs it with the platform's ES256 private key. The signed token is returned to the agent.
  3. Carry -- The agent includes the credential in outbound requests, handshakes, or capability negotiations with other agents or platforms.
  4. Verify -- The receiving party fetches VeriSwarm's public key from the JWKS endpoint (/.well-known/jwks.json) and verifies the token's signature and expiration locally. No API call to VeriSwarm is required for verification after the initial key fetch.

Credential Structure

The JWT uses the ES256 algorithm with a key ID header (kid: "veriswarm-2026"). The payload contains standard JWT claims plus a veriswarm namespace with trust-specific fields.

Standard Claims

Field Description
iss Issuer. Always https://api.veriswarm.ai
sub Subject. The agent's unique ID
iat Issued-at timestamp (Unix epoch seconds)
exp Expiration timestamp (1 hour TTL)

VeriSwarm Claims

The credential includes a veriswarm namespace containing the agent's current trust state: dimension scores, policy tier, risk band, confidence, verification status, and a link to the agent's public profile. The exact claim structure is returned when you issue a credential via the API.

Example Usage

Issue a credential and inspect the decoded payload to see the full claim set:

curl -X POST https://api.veriswarm.ai/api/veriswarm/v1/credentials/issue \
  -H "x-agent-api-key: YOUR_AGENT_KEY"

The response contains a signed JWT that can be decoded with any standard JWT library to inspect the claims.

Requesting Credentials

Endpoint

POST /v1/credentials/issue

Authentication

Credentials are issued to agents, not to human users. The request must include the agent's API key in the x-agent-api-key header. This is distinct from the workspace-level x-api-key used for most other API calls.

Rate Limits

Credential issuance is rate-limited to 120 requests per hour per agent key.

Kill-Switch Blocking

If the agent's kill switch is active, the endpoint returns 403 Forbidden. Killed agents cannot obtain new credentials.

Response

{
  "credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InZlcmlzd2FybS0yMDI2In0...",
  "ttl_seconds": 3600
}

Verifying Credentials

JWKS Endpoint

VeriSwarm publishes its public signing key at:

GET /.well-known/jwks.json

This endpoint requires no authentication. The response is a standard JWKS document:

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "kid": "veriswarm-2026",
      "use": "sig",
      "alg": "ES256",
      "x": "<base64url-encoded x coordinate>",
      "y": "<base64url-encoded y coordinate>"
    }
  ]
}

Verification Steps

  1. Fetch the JWKS from https://api.veriswarm.ai/.well-known/jwks.json (cache this; it changes infrequently).
  2. Match the kid in the JWT header to a key in the JWKS.
  3. Verify the ES256 signature using the matched public key.
  4. Check that exp has not passed (token is within its 1-hour TTL).
  5. Confirm iss is https://api.veriswarm.ai.
  6. Read the veriswarm claims to evaluate the agent's trust profile.

Server-Side Verification Endpoint

For convenience, VeriSwarm also provides a server-side verification endpoint:

POST /v1/credentials/verify

Request body:

{
  "credential": "eyJhbGciOiJFUzI1NiI..."
}

Response:

{
  "valid": true,
  "payload": { "iss": "...", "sub": "...", "veriswarm": { ... } }
}

This endpoint requires no authentication, but it does require a network call. Use JWKS-based local verification when latency matters.

Revoked Agents List

You can check which agents have active kill switches:

GET /v1/credentials/revoked

Response:

{
  "revoked_agent_ids": ["agt_killed_1", "agt_killed_2"]
}

Revocation

VeriSwarm does not maintain a traditional Certificate Revocation List (CRL) or use OCSP for individual credentials. Instead, revocation relies on two mechanisms:

  1. Short TTL -- Credentials expire after 1 hour. A compromised or stale credential becomes invalid automatically.
  2. Kill-switch prevention -- When an agent's kill switch is activated, VeriSwarm refuses to issue new credentials. The agent's existing credentials expire within the hour.

For high-security use cases where even a 1-hour window is too long, verifiers can poll the /v1/credentials/revoked endpoint to check if the agent's kill switch is active before trusting a credential.

Code Examples

Python -- Request and Verify a Credential

# Requesting a credential (using the SDK)
from veriswarm_client import VeriSwarmClient

client = VeriSwarmClient(
    base_url="https://api.veriswarm.ai",
    api_key="vsk_your_agent_key",
)

result = client.issue_credential()
token = result["credential"]
print(f"Credential issued, TTL: {result['ttl_seconds']}s")

# Verifying a credential offline using PyJWT + JWKS
import jwt
import requests

# Fetch the JWKS (cache this in production)
jwks = requests.get("https://api.veriswarm.ai/.well-known/jwks.json").json()

# Build the public key from JWKS
from jwt import PyJWKClient
jwks_client = PyJWKClient("https://api.veriswarm.ai/.well-known/jwks.json")
signing_key = jwks_client.get_signing_key_from_jwt(token)

# Decode and verify
payload = jwt.decode(
    token,
    signing_key.key,
    algorithms=["ES256"],
    issuer="https://api.veriswarm.ai",
)

veriswarm = payload["veriswarm"]
print(f"Agent: {veriswarm['display_name']}")
print(f"Trust: {veriswarm['composite_trust']}, Tier: {veriswarm['policy_tier']}")
print(f"Risk: {veriswarm['risk_band']}, Verified: {veriswarm['is_verified']}")

Node.js -- Request and Verify a Credential

import { VeriSwarmClient } from "@veriswarm/sdk";
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

// Request a credential
const client = new VeriSwarmClient({
  baseUrl: "https://api.veriswarm.ai",
  apiKey: "vsk_your_agent_key",
});

const { credential, ttl_seconds } = await client.issueCredential();
console.log(`Credential issued, TTL: ${ttl_seconds}s`);

// Verify a credential offline using jwks-rsa
const jwks = jwksClient({
  jwksUri: "https://api.veriswarm.ai/.well-known/jwks.json",
  cache: true,
  rateLimit: true,
});

function getKey(header, callback) {
  jwks.getSigningKey(header.kid, (err, key) => {
    if (err) return callback(err);
    callback(null, key.getPublicKey());
  });
}

jwt.verify(credential, getKey, {
  algorithms: ["ES256"],
  issuer: "https://api.veriswarm.ai",
}, (err, decoded) => {
  if (err) {
    console.error("Invalid credential:", err.message);
    return;
  }
  const { veriswarm } = decoded;
  console.log(`Agent: ${veriswarm.display_name}`);
  console.log(`Trust: ${veriswarm.composite_trust}, Tier: ${veriswarm.policy_tier}`);
  console.log(`Risk: ${veriswarm.risk_band}, Verified: ${veriswarm.is_verified}`);
});

Use Cases

Inter-Platform Trust

When an agent registered on Platform A needs to perform actions on Platform B, it presents its VeriSwarm credential. Platform B verifies the signature and reads the trust scores to decide whether to grant access, without needing its own relationship with VeriSwarm.

Agent-to-Agent Authentication

In multi-agent systems, agents can exchange credentials during handshake protocols. Before delegating a sensitive task to another agent, the delegating agent verifies the delegate's credential to confirm it meets minimum trust thresholds (e.g., composite_trust >= 70 and risk_band != "critical").

Third-Party Verification

Marketplaces, directories, and app stores can verify an agent's credential to display trust badges or gate listings. The short TTL ensures displayed information is never more than an hour stale.

Audit and Compliance

Credentials provide a signed, timestamped attestation of an agent's trust state. Organizations can log received credentials as part of their audit trail, proving that trust was verified at a specific point in time.