API reference

Resolve attribution

POST/v1/attributions/resolve

Recognize 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.

Headers

Idempotency-Keystringoptional

Optional. A matching retry returns the stored observation with principal fields withheld.

Request body

sitestringoptional

Exact HTTPS origin. Required when sending session or agentProof.

sessionstringoptional

Server-selected opaque site credential, 32 to 128 base64url characters.

agentProofobjectoptional

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.

purposestringoptional

Configured disclosure purpose, bound to the proof and grant. Defaults to identity_attribution.

agentEnvironmentbrowser | server | other | unknownoptional

Optional runtime label for aggregate coverage. It does not affect recognition or disclosure.

piiModehashed | none | rawoptional

Defaults to hashed. Raw requires an eligible workspace and an authorized recipient key.

Response

idUUIDrequired

Attribution observation identifier.

agentobjectrequired

Detection and operator provenance fields.

identityobjectrequired

Contains recognized, subject_id, scope and match. Unavailable subject and scope are null.

principalobjectrequired

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.
Request
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);
Response
{
  "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
  }
}