Purposes and Projections

Purposes and Projections

The idea in one paragraph

Nobody should receive a whole person just because they asked. A receptionist needs a name and a company; a clinical trial needs credentials; a regulator needs obligations and deadlines. In IGL an application states its purpose, and the platform returns the projection of an identity that the purpose justifies: the permitted node types, below a sensitivity ceiling, only where consent exists, only where the data may legally be served. Everything else is withheld, counted, and explained on request.

The purpose profiles every tenant starts with

Purpose	Meant for	Node types it permits	Sensitivity ceiling
identity-introduction (default)	Greeting, routing and addressing the person correctly	Person, Organization, Role, Jurisdiction	internal
directory-lookup	Rosters, mentions and org charts	Person, Role	internal
scientific-research	Qualification checks and study eligibility	Person, Organization, Role, Jurisdiction, Credential, Facility	confidential
regulatory-filing	Deadline tracking and filing preparation	Person, Organization, Role, Jurisdiction, Facility, Obligation	confidential

GET /purposes lists them for your tenant; GET /purposes/{purposeId} describes one. The sensitivity scale is public, internal, confidential, restricted. Each node type has a default sensitivity (a Credential is confidential, a Jurisdiction is public, a Person is internal) and a tenant can set it per node.

The four gates, exactly

Every node reachable from the identity (up to maxDepth, default 1, at most 4) is tested in this order, and the first failure is the recorded reason:

1. Purpose. The profile permits this node type. A Credential under identity-introduction fails here.
2. Sensitivity. The node's sensitivity is at or below the profile's ceiling. A restricted node fails under every default profile.
3. Consent. An active consent record exists for this identity and this purpose. New Person and Organization identities get consent for the tenant's default purposes at creation; everything else is granted explicitly by an administrator (POST /admin/consents) and can be revoked the same way.
4. Jurisdiction. The tenant's transfer policy allows this sensitivity to be served where the caller is. Callers in the tenant's home jurisdiction pass. Callers elsewhere are limited to public and internal unless the tenant's policy says otherwise for that country.

A node that passes all four is admitted, up to the nodeBudget (default 50, at most 500). Past the budget the response is marked truncated and the remainder is counted as withheld.

What a projection response contains

{
  "identityId": "4b1e...",
  "purpose": "identity-introduction",
  "nodes": [ { "id": "...", "type": "Person", "label": "Maria Santos", "attributes": {...}, "confidence": 1, "status": "certified" }, ... ],
  "edges": [ { "fromId": "...", "type": "employed_by", "toId": "...", "status": "certified" } ],
  "truncated": false,
  "emptyWarning": null,
  "withheld": { "Credential": 1 },
  "governance": { "...": "the signed receipt" }
}

edges only ever contains certified relationships between admitted nodes; a proposed relationship, which is what a model would create, never appears. emptyWarning is set when the identity exists but nothing passed, with the reason ("no consent record covers this purpose" or "no node passed the gates"), so an empty answer is never silent. governance is the receipt described in Governance Receipts and Audit; its outputHash is the SHA-256 of nodes.

Explain: show the work

GET /identities/{id}/projection/explain?purpose=... returns considered: every node that was looked at, the result of each gate (pass, fail or skipped because an earlier gate failed; the first gate is named nodeType in the output), and firstFailure, along with truncated. It does not repeat the projection; call the projection endpoint for the nodes and the receipt. This is the page a privacy officer wants, and it is also how you debug "why can't my app see X" in one request instead of a support ticket.

Obligations and consents

GET /identities/{id}/obligations?purpose=regulatory-filing returns the obligations in scope, each marked attested or proposed. A proposed obligation is a model's suggestion of a deadline; an attested one was confirmed by a person. Applications should never treat a proposed date as a due date, and the response makes the difference impossible to miss.

GET /identities/{id}/consents lists the consent records behind the gate, with who granted them, for what scope and until when. Administrators grant and revoke through POST /admin/consents.

Why this matters commercially

It is the difference between "we integrated with the identity system" and "we can show, for any request, exactly what a third party received and why". A customer can give a partner a read-only key, grant the identities involved consent only for the purpose the partner needs, and know, without reviewing code, that the partner cannot see credentials or obligations under any purpose. A regulator can be handed the explain output for one request. And the same identity serves every application without copying data into each one.

Try it

Quickstart: the API walks through signup, an organization, a certified relationship, a projection and an explain in five commands. The interactive version with no account at all is the User Center on id-me.ai, which runs the same resolver in your browser and shows the projection under each purpose side by side.