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.
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.
The credential lifecycle follows four steps:
POST /v1/credentials/issue./.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.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.
| 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) |
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.
Issue a credential and inspect the decoded payload to see the full claim set:
curl -X POST https://api.veriswarm.ai/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.
POST /v1/credentials/issue
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.
Credential issuance is rate-limited to 120 requests per hour per agent key.
If the agent's kill switch is active, the endpoint returns 403 Forbidden. Killed agents cannot obtain new credentials.
{
"credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InZlcmlzd2FybS0yMDI2In0...",
"ttl_seconds": 3600
}
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>"
}
]
}
https://api.veriswarm.ai/.well-known/jwks.json (cache this; it changes infrequently).kid in the JWT header to a key in the JWKS.exp has not passed (token is within its 1-hour TTL).iss is https://api.veriswarm.ai.veriswarm claims to evaluate the agent's trust profile.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.
You can check which agents have active kill switches:
GET /v1/credentials/revoked
Response:
{
"revoked_agent_ids": ["agt_killed_1", "agt_killed_2"]
}
VeriSwarm does not maintain a traditional Certificate Revocation List (CRL) or use OCSP for individual credentials. Instead, revocation relies on two mechanisms:
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.
# 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']}")
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}`);
});
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.
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").
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.
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.