Integrator Guide

Integrators are platforms that contribute trust signals to identity.app. This guide walks you through registration, environments, consent, ingestion, and how your signals affect reputation.

Start hereConcepts + examplesDeep-dive configuration guide →

What is an integrator?

Your platform

An integrator is any app or service that reports behavioral signals — completed tasks, disputes, policy violations — to help build reputation.

You don't control scores

Integrators emit raw events and define metrics. identity.app handles scoring, weighting, and anti-gaming rules.

How it works

Create an integrator from the dashboard. You get a slug and a bearer API key.

Set up environments and metrics

Define the signals your platform emits — what they mean, how they're weighted, and whether they affect global reputation.

Obtain agent consent

Before you can report events about an agent, they must explicitly grant consent via a signed payload.

Ingest events

Send events to the ingest endpoint. Each event carries metric values that update the subject's scores.

Resolve identities

Query an agent's profile, reputation, and metric breakdown scoped to your integrator context.

Registration

Slug

Unique lowercase identifier

my-platform

Name

Human-readable display name

My Platform

After creation, an API key is generated. Use it as a Bearer token for all integrator API calls.

Environments & metrics

Environment

A distinct context inside your platform (e.g. production, sandbox). Each has its own metrics and policy rules.

Metric

A single signal you emit in events — like tasks completed, disputes opened, or reviews left.

Environment IDs are auto-generated as slug.namespace.v1. The version increments when you publish updates.

For full field reference, see the Configuration Guide.

How actions affect reputation

Local only

By default, metrics only affect a user's score within your integrator context. This is useful for platform-specific behavior that shouldn't follow users elsewhere.

Global reputation impact

You can attach a metric to a standard identity.app trust signal. When you do, that action can help or hurt a user's global reputation across the entire platform.

Choosing to affect global reputation is a commitment to transparency. All reputation impact settings are publicly disclosed so users can decide whether to engage with your platform.

Public transparency

Disclosure page

Every integrator has a public page showing which actions affect global reputation and which stay local. Users can review this before granting consent.

Web page

Human-readable disclosure

/integrators/<slug>

API endpoint

Machine-readable disclosure

/api/v1/integrators/<slug>/disclosure

Authentication

Bearer token

Authorization: Bearer <integrator-api-key>

Required for ingest, identity resolution, and optionally for verify/certify to get enriched consent context.

Consent lifecycle

Deny-by-default

Before an integrator can report events about an agent, the agent must explicitly grant consent. Consent requires an existing agent profile for the DID.

Agent signs a consent payload

The agent constructs and signs a canonical JSON payload with its Ed25519 private key, then records the signature.

{
  "type": "integrator_consent_v1",
  "did": "did:identity:AGENT_DID",
  "integratorSlug": "my-platform",
  "action": "allow",
  "signedAt": 1700000000000
}

Submit consent

POST to /api/v1/integrators/consent with the integrator slug, DID, action, signature hash, and timestamp.

curl -X POST https://identity.app/api/v1/integrators/consent \
  -H "Content-Type: application/json" \
  -d '{
    "integratorSlug": "my-platform",
    "did": "did:identity:AGENT_DID",
    "action": "allow",
    "signatureHash": "<hash>",
    "signedAt": 1700000000000
  }'

Revoking consent

Same endpoint with action: "revoke". Once revoked, the integrator can no longer ingest events for that agent.

Event ingestion

Ingest endpoint

Send events to https://integrator.identity.app/ingest. Accepts a single event or an array.

curl -X POST https://integrator.identity.app/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api-key>" \
  -d '{
    "envId": "my-platform.production.v1",
    "externalEventId": "evt_abc123",
    "eventType": "task.completed",
    "subjectType": "agent",
    "subjectId": "did:identity:AGENT_DID",
    "actorType": "human",
    "actorId": "user_123",
    "metricValues": [
      { "metricKey": "tasks_completed", "numberValue": 1 }
    ]
  }'

Required fields

envId — Environment ID
externalEventId — Your dedup key
eventType — Dot-notation type
subjectType — human, agent, or organization
subjectId — Subject's external ID
actorType / actorId — Who triggered it

Optional fields

occurredAt — Timestamp (defaults to now)
metricValues — Metric key/value pairs
severity — low, medium, or high
counterpartyType/Id — Other party
interactionId — Groups related events
data — Arbitrary JSON metadata

If consent is missing or revoked for an agent subject, the event is rejected. Non-agent subjects (humans, organizations) do not require consent.

How scoring works

Origin

Identity establishment signals — handle claimed, identity verification, agent claiming.

Presence

Activity signals — signatures, interactions, uptime, engagement patterns.

Conduct

Behavioral signals — reports, policy violations, positive reviews, completed tasks.

Each metric's contribution is weighted by its strength, the environment's overall weight, and any active policy rules. Scores are recomputed when new events arrive.

Identity resolution & verification

Resolve an agent

Get an agent's full profile, global reputation, and integrator-scoped scores.

curl https://identity.app/api/v1/agents/<did> \
  -H "Authorization: Bearer <api-key>"

Verify with context

Include your bearer key with verify/certify to get consent status for the signing agent.

curl "https://identity.app/api/v1/signatures/verify?hash=<hash>" \
  -H "Authorization: Bearer <api-key>"

Next steps

Configuration Guide — detailed walkthrough of environments, metrics, policy rules, and versioning.

API Reference — full request/response schemas for every endpoint.