API reference
/v1/attributions/resolveRecognize an enrolled agent or site session and resolve authorized principal claims.
Requires a bearer key with attribution:read. Unknown identity is a successful HTTP 200 result. Send an exact HTTPS origin when submitting evidence. The maximum JSON body is 8,192 bytes.
A fresh network proof recognizes an enrolled agent and returns a site-scoped subject. Principal details require disclosure to be enabled in the deployment and a single active grant for that recipient and purpose. A site session can establish recurrence within one site.
Exact HTTPS origin. Required when sending session or agentProof.
Server-selected opaque site credential, 32 to 128 base64url characters.
Send either a network proof with iss and agentKey or a site proof with linkId. Both carry a UUID nonce, Unix-second issuedAt, and an Ed25519 signature.
Configured disclosure purpose, bound to the proof and grant. Defaults to identity_attribution.
Optional runtime label for aggregate coverage. It does not affect recognition or disclosure.
Defaults to hashed. Raw requires an eligible workspace and an authorized recipient key.
Attribution observation identifier.
Detection and operator provenance fields.
Contains recognized, subject_id, scope and match. Unavailable subject and scope are null.
Contains status and nullable email, email_verified, current_delegation_verified and document_verified.
- The authorized example comes from the isolated Test demo. Email requires consent to retain and share the verified address, an eligible plan, the attribution:email scope, and raw mode. A recognized result is evidence for your access policy.
- 400 invalid input, 401 inactive or missing credential, 403 missing scope or disallowed disclosure, 409 conflicting idempotency key, 429 rate limited, 503 service unavailable.
import { Chitmark } from "@chitmark/sdk";
const chitmark = new Chitmark({ apiKey: process.env.CHITMARK_API_KEY! });
const request = new Request("https://app.example.com/signup");
const result = await chitmark.attribution.resolve({
request,
session: "example_session_0123456789abcdefghijklmnop",
});
console.log(result.identity.recognized, result.principal.email);{
"id": "b279f88d-e830-4176-a0db-d0eeeee47d30",
"agent": {
"detected": false,
"provider": null,
"operator_verified": false
},
"identity": {
"recognized": false,
"subject_id": null,
"scope": null,
"match": "none"
},
"principal": {
"status": "unknown",
"email": null,
"email_verified": null,
"current_delegation_verified": null,
"document_verified": null
}
}