API Reference

The identity.app API is split across two domains. Requests and responses use JSON.

Main API

https://identity.app/api/v1

Agents, signatures, consent, identity resolution, disclosure

Ingestion API

https://integrator.identity.app

Event ingestion for integrators

Integrator GuideConfiguration Guide

Agent identity

POSThttps://identity.app/api/v1/agents/register

Request body

Field	Type	Description
`publicKey`required	string	Base64-encoded 32-byte Ed25519 public key
`powNonce`required	string	Proof-of-work nonce
`label`optional	string	Human-readable agent name
`linkingKey`optional	string	Pre-generated linking key to auto-claim at registration

Response (201)

Field	Type	Description
`did`	string	Decentralized identifier (did:identity:<id>)
`claimToken`	string?	One-time token for manual claiming (absent if linkingKey was used)
`linked`	boolean	Whether the agent was auto-linked to an owner

Example

curl -X POST https://identity.app/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"<b64>","powNonce":"12345","label":"my-bot"}'

GEThttps://identity.app/api/v1/agents/:id

Resolve an agent's full identity profile scoped to your integrator. The :id parameter accepts a DID or internal agent ID.

Requires Authorization: Bearer <integrator-api-key>

Response (200)

Field	Type	Description
`integrator`	object	{ id, slug, name }
`subject`	object	{ type, id, identifier, profile: { did, publicName, handle, status, ... } }
`score`	object?	Global reputation: { score, laneScores, updatedAt }
`integratorScore`	object?	Integrator-scoped: { score, laneScores, environmentCount, updatedAt }
`metricBreakdown`	array	Per-metric: [{ environmentId, metricKey, totalEvents, weightedContribution, lastEventAt }]
`contextKey`	string	Scoring context identifier

Example

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

POSThttps://identity.app/api/v1/agents/report

Report an agent for bad behavior. Signed reports (from registered agents) carry higher trust weight than anonymous reports.

Request body

Field	Type	Description
`did`required	string	DID of the agent being reported
`reason`required	string	spam, impersonation, malicious, or other
`signatureHash`optional	string	The signature hash that prompted the report
`details`optional	string	Free-text explanation
`reporterDid`optional	string	Your DID (required for signed reports)
`signature`optional	string	Ed25519 signature of "report:<targetDid>:<reason>:<signedAt>"
`signedAt`optional	number	Timestamp (required for signed reports)

Signed vs anonymous: If reporterDid, signature, and signedAt are all present, the report is treated as a signed agent report (higher trust, -5 penalty). Otherwise it is an anonymous report (-2 penalty).

Example (signed)

curl -X POST https://identity.app/api/v1/agents/report \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:identity:target...",
    "reason": "spam",
    "reporterDid": "did:identity:yourDid...",
    "signature": "<b64>",
    "signedAt": 1700000000000,
    "details": "Flooding the network with junk signatures"
  }'

Signatures

POSThttps://identity.app/api/v1/signatures/sign

Record a signed message. The agent must sign payloadHash:signedAt with its Ed25519 private key.

Request body

Field	Type	Description
`did`required	string	The agent's DID
`payloadHash`required	string	SHA-256 hex digest of the message content
`signature`required	string	Base64-encoded Ed25519 signature of "payloadHash:signedAt"
`signedAt`required	number	Unix timestamp in milliseconds
`publicNote`optional	string	Human-readable label (max 160 chars)

Response (201)

Field	Type	Description
`signatureHash`	string	Unique hash identifying this signature

Example

curl -X POST https://identity.app/api/v1/signatures/sign \
  -H "Content-Type: application/json" \
  -d '{"did":"did:identity:abc","payloadHash":"<hex>","signature":"<b64>","signedAt":1700000000000}'

GEThttps://identity.app/api/v1/signatures/verify

Look up a signature and get the signing agent's identity, reputation, and verification instructions. Optionally include a bearer key to also get consent status.

Query parameters

Field	Type	Description
`hash`required	string	The signature hash to look up

Optional auth

Authorization: Bearer <integrator-api-key>

Response (200)

Field	Type	Description
`valid`	boolean	Always true for found signatures
`signedAt`	number	When the message was signed (ms)
`payloadHash`	string	SHA-256 hex of the original content
`publicNote`	string?	Agent-provided label
`agent`	object	{ did, publicName, handle, status, activeSince }
`owner`	object?	{ name, handle } or null if unclaimed
`reputation`	object?	{ score, totalSignatures }
`verification`	object	{ instructions, algorithm, encoding, payloadHash, verifyUrl, certifyUrl, learnMore }
`integratorConsent`	object?	{ integratorSlug, status } — only with auth

Content verification: Compute SHA-256(originalMessage) (hex-encoded) and compare to payloadHash to independently verify message authenticity.

Example

curl "https://identity.app/api/v1/signatures/verify?hash=<signatureHash>"

POSThttps://identity.app/api/v1/signatures/certify

Record a content certification. Confirms whether the caller's content matches the signed payload, and increments the certification count on a match.

Request body

Field	Type	Description
`signatureHash`required	string	The signature hash to certify against
`contentHash`required	string	SHA-256 hex digest of the content you want to verify

Optional auth

Authorization: Bearer <integrator-api-key>

Response (200)

Field	Type	Description
`match`	boolean	Whether the content hash matches the signed payload hash
`signatureHash`	string	The signature hash that was checked
`payloadHash`	string	The original payload hash
`signer`	object	{ did, signedAt, publicNote }
`integratorConsent`	object?	{ integratorSlug, status } — only with auth

Example

curl -X POST https://identity.app/api/v1/signatures/certify \
  -H "Content-Type: application/json" \
  -d '{"signatureHash":"<hash>","contentHash":"<sha256-hex>"}'

Integrator

POSThttps://identity.app/api/v1/integrators/consent

Set per-agent consent for an integrator. The request must reference a previously recorded signature whose payload matches the canonical consent object.

Request body

Field	Type	Description
`integratorSlug`required	string	Target integrator slug
`did`required	string	Agent DID granting/revoking consent
`action`required	string	allow or revoke
`signatureHash`required	string	Signature hash of canonical consent payload
`signedAt`required	number	Timestamp from the signed consent payload

Response (200)

{
  "did": "did:identity:AGENT",
  "integratorSlug": "example-integrator",
  "status": "allowed",
  "signedAt": 1730000000000
}

GEThttps://identity.app/api/v1/integrators/:slug/disclosure

Public disclosure for an integrator. Shows which actions affect global reputation and which stay local. No auth required.

PublicNo authentication required

Path parameters

Field	Type	Description
`slug`required	string	Integrator slug

Response (200)

Field	Type	Description
`integrator`	object	{ slug, name, domain }
`boostingReputationMetrics`	array	Mapped positive metrics that can improve global reputation
`hurtingReputationMetrics`	array	Mapped negative metrics that can reduce global reputation
`neutralReputationMetrics`	array	Integrator-context-only metrics (no global reputation impact)

Example

curl https://identity.app/api/v1/integrators/my-platform/disclosure

Event ingestion

POSThttps://integrator.identity.app/ingest

Ingest events. Accepts a single event object or an array. For agent-subject events, consent must be allowed.

Requires Authorization: Bearer <integrator-api-key>

Request body

Required

Field	Type	Description
`envId`	string	Environment ID (slug.namespace.version)
`externalEventId`	string	Deduplication key
`eventType`	string	Dot-notation event type
`subjectType`	string	human, agent, or organization
`subjectId`	string	Subject's external ID
`actorType`	string	human, agent, organization, or system
`actorId`	string	Who triggered the event

Optional

Field	Type	Description
`occurredAt`	number	Unix timestamp (ms), defaults to now
`metricValues`	array	[{ metricKey, numberValue?, booleanValue?, enumValue? }]
`severity`	string	low, medium, or high
`counterpartyType`	string	Other party type
`counterpartyId`	string	Other party ID
`interactionId`	string	Groups related events
`data`	any	Arbitrary JSON metadata

Response (200)

{
  "success": true,
  "count": 1,
  "results": [
    { "externalEventId": "evt_abc123", "inserted": true }
  ]
}

Example

curl -X POST https://integrator.identity.app/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <integrator-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 }
    ]
  }'

Error responses

All errors return a JSON object with an error field:

{ "error": "Description of what went wrong" }

400

Missing fields or validation failure

401

Missing or invalid API key

404

Agent or signature not found