Integrator Configuration Guide

This guide explains how to model your platform in identity.app so your events become meaningful trust signals. It is written for people who are new to this system: first we cover concepts, then we cover how to configure each field.

Start hereConcepts firstExamples includedField reference below

What this configuration does

As an integrator, you send events (example: completed job, dispute opened, spam report). Configuration is where you define how those events become trust signals.

which signals exist,
whether they are positive, negative, or neutral,
how much each signal should matter,
what anti-gaming guardrails should apply.

Concepts at a glance

Integrator

Your product or platform.

Example: a marketplace app

Environment

A category of behavior inside your platform.

Example: payments, moderation, reliability

Metric

A single signal you emit in events.

Example: buyer confirms delivery and leaves a positive rating

Policy rule

A control to limit abuse or runaway scoring.

Example: count only the first 3 repeated actions in a 24h window

How configuration flows in practice

Pick your trust dimensions

Create 1-3 environments that map to how trust works in your product.

Define clear metrics

Add a small set of metrics in each environment. Start focused, not exhaustive.

Set local scoring behavior

Decide whether each metric is good, bad, or neutral for your platform, then assign conservative local weights.

Choose global reputation impact

For each metric, decide whether it should stay local or affect global identity.app reputation, since this can influence whether users choose to interact with your platform.

Apply policy rules

Add anti-gaming controls so repeated or coordinated behavior cannot dominate reputation.

Ship and iterate by version

Deploy, monitor outcomes, then publish a new version when you need to adjust scoring logic.

Worked example (marketplace)

Environment: transactions

job_completed - positive signal that a task was finished.
payment_dispute - negative signal that trust may be at risk.
late_delivery - negative signal with moderate weight.

Policy example

Apply max_env_contribution so this one environment cannot dominate total reputation by itself.

Field reference

Environment fields

Field	Required	Meaning	Example	Limits
`namespace`	Yes	Stable identifier in snake_case	payments	/^[a-z][a-z0-9_]{0,63}$/
`description`	No	Human-readable context for operators	Payment behavior and disputes	Keep concise and specific
`aggregationWeight`	Yes	How strong this environment is overall	1.0	0.1..5.0

Metric fields

Field	Required	Meaning	Example	Limits
`metricKey`	Yes	Machine identifier for the signal	job_completed	Unique in environment
`label`	Yes	UI label	Jobs completed	Clear and short
`lane`	Yes	Trust lane this metric contributes to	conduct	origin \| presence \| conduct
`valueType`	Yes	Expected value payload type	number	number \| boolean \| enum
`polarity`	Yes	Whether higher contribution is good or bad	positive	positive \| negative \| neutral
`aggregation`	Yes	How metric values combine over time	sum	sum \| avg \| count \| rate
`global reputation impact`	No	Whether this metric also affects global identity.app reputation	None or transaction_completed	None = local only
`defaultWeight`	Yes	Metric-level strength	1.0	0.1..10.0

Policy rules quick reference

Pairwise diminishing

Use when the same two actors can generate many repeated events. Repeated interactions get progressively less influence.

Use case: prevent score farming between two colluding accounts.

Max contribution

Use when one environment should not be able to dominate the entire trust profile.

Use case: cap the maximum influence of one area like payments or moderation.

Severity multiplier

Use when the same metric can arrive with low/medium/high severity and should scale differently by severity.

Use case: severe violations count much more than minor incidents.

Current limit: 1-3 policy rules per environment, with only one instance per rule type.

AI pre-generation vs manual setup

Pre-generate with AI

Best when you need a fast first draft. You can edit every field before saving.

Configure manually

Best when you already know your taxonomy or need strict control from day one.

For integrators that already have environments, AI pre-generation creates one new environment draft at a time.

Versioning and rollout strategy

Environment IDs follow <slug>.<namespace>.v<n>.

Upgrading creates a new version (for example v1 to v2) and marks the previous one deprecated.
Ingest accepts active and deprecated versions to support safe rollout.
Recommended rollout: publish new version, update callers, monitor, then decommission old versions when ready.

Ingest identity conventions

Keep actor/subject identity formatting consistent before rollout so ingest validation and analytics stay predictable.

If actorType is agent, set actorId to a valid DID.
If actorType is system, use sys:<integratorSlug>:<component>. Short form sys:<integratorSlug> is accepted and normalized to :main.
For agent-subject events, consent remains deny-by-default and consent grants require an existing agent profile for that DID.

Before you hit save

Quick checklist

Namespace format is valid and unique in form.
At least one metric exists.
Metric keys are unique and labels are non-empty.
Weights are inside allowed ranges.
Policy keys and numeric values are valid.

Common mistakes

Too many metrics before you validate signal quality.
Ambiguous keys like score or rank.
High default weights without observed production behavior.
No policy rules for high-volume interactions.