Documentation
Advanced reference for Ed25519 proof serialization and integrations that sign outside the SDK.
On this page
Follow the Alice walkthrough to see the end-to-end flow. Use a separate workspace, exact HTTPS origin, and read key at each site. The enrolling workspace can also be the first recipient. Bind the agent once in the enrollment environment, then sign a new proof for each site visit. Create and revoke each site's grant independently.
The local Alice demo enables disclosure for synthetic Test data so you can exercise recognition and recipient grants.
If you are integrating with the TypeScript SDK, use the signing helpers in the two-website example. The wire format below is for interoperable signers.
Use an enrolled principal with a public Ed25519 key and an authenticated OpenID Connect account. Share only public JWK fields kty, crv, and x. Keep the private keys with their respective controllers.
Submit { kind: "network_agent", enrollmentId, agentKey, expiresAt, principalProof, agentProof } to POST /v1/identity-links with an attribution:write key in the enrolling workspace. Use Unix seconds for expiresAt, no later than 90 days after enrollment. Keep the returned id as agentId for grant and lifecycle operations.
For principalProof, sign ["chitmark-network-bind-v1", sponsorOrg, environment, enrollmentId, agentKey.x, expiresAt, null, null] with the principal key. For agentProof, sign the same fields with the new agent key and replace the first element with "chitmark-network-accept-v1". All signatures in this guide cover the UTF-8 bytes of a compact JSON array and use unpadded base64url.
To rotate, include rotation: { agentId, previousKey } and replace the last two signed elements with agentId, previousKey.x. The previous key stops resolving when the rotation commits. The agent keeps its existing site subjects and current grants. An expired or revoked binding requires a new binding with a fresh key.
Use the SDK's signing helpers to build the signed messages. signAttributionNetworkBinding takes separate principal and agent signers. signAttributionNetworkGrant uses the principal signer. Pass the resulting request objects to attribution.createLink with the appropriate workspace write key.
The agent uses signAttributionNetworkProof to create a new proof for each visit. Each signing callback receives the message bytes and returns a 64-byte Ed25519 signature. The helper generates the nonce and timestamp and encodes the signature. The recipient configures the same purpose and data mode, which default to identity_attribution and hashed.
import { createPrivateKey, createPublicKey, sign } from "node:crypto";
import { readFile } from "node:fs/promises";
import { signAttributionNetworkProof } from "@chitmark/sdk";
const privateKey = createPrivateKey({
format: "jwk",
key: JSON.parse(await readFile(process.env.AGENT_KEY_FILE!, "utf8")),
});
const { x } = createPublicKey(privateKey).export({ format: "jwk" });
const recipient = {
organizationId: process.env.CHITMARK_RECIPIENT_ORG!,
keyId: process.env.CHITMARK_RECIPIENT_KEY_ID!,
site: process.env.CHITMARK_SITE!,
};
const proof = await signAttributionNetworkProof({
agentKey: { kty: "OKP", crv: "Ed25519", x: x! },
environment: "test",
recipient,
}, (message) => sign(null, message, privateKey));
await fetch(new URL("/agent-task", recipient.site), {
headers: { "Chitmark-Agent-Proof": JSON.stringify(proof) },
});The agent signs ["chitmark-network-resolve-v1", "chitmark-agent-key-v1", agentKey.x, recipientOrg, environment, recipientKeyId, site, purpose, nonce, issuedAt, piiMode] with its active key and sends Chitmark-Agent-Proof: {"iss":"chitmark-agent-key-v1","agentKey":{...},"nonce":"...","issuedAt":0,"signature":"..."}. The signature has a 60-second window. Generate a fresh UUID nonce per request. The API consumes each proof once.
Use the exact HTTPS origin, recipient workspace ID and read key record ID. The recipient supplies its configured purpose and piiMode to resolve. Defaults are identity_attribution and hashed. The signed values must agree with the receiving integration. Keep the actual recipient API key on the recipient server.
Agent proof establishes control of the enrolled key for this recipient. The public key in the inbound proof is visible to the receiving server. Avoid logging proof headers. Your application still performs its own authorization.
The principal signs ["chitmark-network-grant-v1", sponsorOrg, environment, agentId, recipientOrg, recipientKeyId, site, purpose, emailConsent, expiresAt]. The recipient accepts it using its own attribution:write key and sends { kind: "network_grant", agentId, recipientKeyId, site, purpose, emailConsent, expiresAt, principalProof } to POST /v1/identity-links. Grant expiry is at most 30 days ahead and cannot exceed the agent binding expiry.
A single active grant for that site, key, and purpose permits principal status and applicable verification metadata. If overlapping grants match, principal data is withheld until only one is active. For email, the principal must also consent to retaining the verified address and to sharing it with this recipient. The recipient must be eligible for raw mode and use a key with attribution:email. Principal disclosure requires explicit enablement in the API deployment.
The recipient or enrolling workspace can revoke the grant using its returned ID. The enrolling workspace can revoke the agent using its agent ID, which revokes all associated grants. Removing the original enrollment also removes the association. New requests check current state. Stored observations and retries never return network identity or principal claims.
Start here when you want a verified association between an agent and an account. Use an opaque site session for session-only continuity.
1. Enroll the account. Open Dashboard → Agent Attribution → Enrollment. Generate an Ed25519 key pair for the principal and paste its public JWK under Advanced · Principal signing key. Select Continue to identity provider and sign in to the external account you want to enroll. Copy the Workspace ID as organizationId and the authenticated enrollment ID as enrollmentId. Keep the principal private key with the account owner. Enrollment belongs to the workspace. The optional Stripe Identity check runs in the provider mode shown in Enrollment and does not grant agent authorization.
2. Choose the agent and recipient. Generate a separate Ed25519 key pair for the agent. The agent keeps that private key. Create an attribution:read test key for the backend that will resolve the proof. Copy its key record ID (key_…) from Dashboard → Keys and use it as recipientKeyId. The backend keeps the bearer credential (ck_test_…). Use test as the environment and an exact HTTPS origin such as https://app.example.com as the site.
3. Authorize the link. The account owner signs the UTF-8 bytes of JSON.stringify(["chitmark-attribution-link-v1", organizationId, environment, enrollmentId, site, agentKey.x, recipientKeyId, emailConsent, expiresAt]) with the principal private key. Use the agent public JWK for agentKey, start with emailConsent: false, and choose a Unix-second expiry up to 30 days ahead. Send the grant and its unpadded base64url signature as principalProof to POST /v1/identity-links using an attribution:write key. Save the returned id as linkId.
4. Resolve a request. The agent signs the UTF-8 bytes of JSON.stringify(["chitmark-attribution-resolve-v1", organizationId, environment, site, linkId, nonce, issuedAt, piiMode]) with its own private key. Use a new UUID for nonce and the current Unix time in seconds for issuedAt. The receiving backend calls POST /v1/attributions/resolve with the linked read credential, the same site and piiMode, and agentProof: { linkId, nonce, issuedAt, signature }. Encode the signature as unpadded base64url and send the proof within 60 seconds.