Agent Assertion · Ed25519

Authenticate an Agent without exporting its signing key

The registered Agent signs a short-lived assertion locally, then sends only the compact assertion to POST https://api-testnet.velarumpay.com/v1/agent-auth/token.

Protected header and claims

Field	Rule
`alg`	Exactly `EdDSA`.
`typ`	Exactly `JWT`.
`kid`	The active registered credential identifier.
`iss`	Registered Agent ID.
`sub`	Stable local client ID, recorded into the issued AuthContext.
`aud`	`https://api-testnet.velarumpay.com/v1/agent-auth/token`.
`iat`, `exp`	Integer Unix seconds; lifetime is at most five minutes.
`jti`	Unique per assertion; replay is rejected.
`scope`	A subset of Agent, credential, and client policy.

Local signer boundary

const client = createVelarumPayClient({
  baseUrl: "https://api-testnet.velarumpay.com",
  agentAuth: {
    agentId, clientId, kid, scopes,
    keyHandle: secureKeyHandle,
    signer: ({ data, keyHandle }) => secureSigner.sign(data, keyHandle)
  }
});

The callback receives UTF-8 bytes for base64url(protected header).base64url(claims). Return the raw Ed25519 signature bytes or base64url signature. Do not return, log, upload, or serialize key material.

Secret-free fixed vector

Download the deterministic mock serialization vector. It includes the canonical signing input and a deliberately invalid all-zero mock signature. It proves serialization without publishing a signing key and must not be sent to a live API.

Failure behavior

401 may trigger one coordinated refresh. 403, revoked/expired credentials, invalid audience, clock skew, malformed signatures, and duplicate JTI fail closed. SDK errors and retries redact the compact assertion and returned token.