AI Agent Integration (MCP Server)

Documentation Index

Fetch the complete documentation index at: https://docs.didit.me/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Self-register via programmatic API (no browser needed, no 2FA on the programmatic accounts the MCP creates).
• Configure verification workflows via API (POST /v3/workflows/).
• Create and manage sessions programmatically (POST /v3/session/, GET /v3/session/{sessionId}/decision/, PATCH /v3/session/{sessionId}/update-status/).
• Monitor billing and top up credits via API (GET /v3/billing/balance/, POST /v3/billing/top-up/).
• Build complete integrations end-to-end without human intervention — pair the MCP server with the one-prompt integration for hands-off setup.

​

Two ways to use Didit from an agent

​

Setup

​

1. Install the MCP server

{
  "mcpServers": {
    "didit": {
      "command": "npx",
      "args": ["@didit-protocol/mcp-server"],
      "env": {
        "DIDIT_API_KEY": "your_api_key_here"
      }
    }
  }
}

​

2. Get your API key

1. Agent calls didit_register with your email and a password (≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special).
2. You receive a 6-character alphanumeric code via email (15-minute TTL).
3. Agent calls didit_verify_email with the code.
4. The response includes the organisation, a default application, and the application’s api_key.

​

Available tools

​

Auth

​

Sessions

​

Workflows

​

Questionnaires

​

Users & businesses

​

Billing

​

Lists (blocklist / allowlist / custom)

​

Webhook destinations

​

Transactions (Transaction Monitoring)

​

Standalone APIs

​

How responses are shaped

1. A status.updated webhook (recommended — see below), OR
2. didit_get_session_decision (polling, only as a fallback).

{
  "session_id": "uuid",
  "status": "Approved",
  "session_kind": "user",
  "id_verifications": [
    { "node_id": "first_id", "status": "Approved", "first_name": "Jane", "...": "..." }
  ],
  "liveness_checks":  [ { "node_id": "first_liveness",  "status": "Approved", "score": 95.4 } ],
  "face_matches":     [ { "node_id": "first_face_match","status": "Approved", "score": 96.1 } ],
  "aml_screenings":   [ { "node_id": "first_aml", "status": "Approved", "entity_type": "person", "total_hits": 0, "hits": [] } ],
  "reviews": []
}

​

Auth failures (agent-visible)

HTTP 403
{ "detail": "You do not have permission to perform this action." }

​

Handling webhooks asynchronously

1. The agent calls didit_create_webhook_destination once with the user’s public HTTPS endpoint, webhook_version: "v3", and a subscribed_events array (typically ["status.updated", "data.updated"]). The response includes a secret_shared_key — the agent should hand it to the user to store as DIDIT_WEBHOOK_SECRET.
2. The user’s backend verifies the canonical X-Signature-V2 header on every delivery: shortenFloats → sortKeys → JSON.stringify(unescaped unicode) → HMAC-SHA256 → timingSafeEqual against the header. Reject if abs(now - X-Timestamp) > 300 seconds.
3. The backend deduplicates on the event_id field (Didit guarantees a unique event_id per delivery attempt). Return 2xx within 5 seconds (Didit’s outbound timeout); move heavy processing to a queue.
4. Didit retries on 5xx and 404 up to 2 times (~1 min, then ~4 min). After that, the delivery is dropped — surface failed deliveries from the Deliveries tab in the console and replay them manually.

​

Example conversation

You: “Set up Didit identity verification for my app with ID scan and liveness.” Agent: I will register a Didit account for you. What email should I use? You: “Use dev@company.com.” Agent: calls didit_register — Check your email for a 6-character code. You: “The code is A3K9F2.” Agent: calls didit_verify_email — Account ready. Saving the api_key as DIDIT_API_KEY. Now creating your workflow… calls didit_create_workflow with ID scan + passive liveness enabled. Your workflow "Standard KYC" is published, workflow_id = 6f2c…. Here is how to create a verification session in your code:

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "6f2c...-stable-id",
    "vendor_data": "internal-user-id",
    "callback":    "https://myapp.com/done"
  }'

Then redirect the user to response.url. Want me to register the webhook destination and scaffold the receiver?

​

Going further

• Use the one-prompt integration. If you want an agent to ship the full integration (backend route + frontend SDK + webhook handler + DB schema), give it the Integration Prompt and watch it walk through the seven steps. The MCP server complements that prompt: the agent reads the prompt, then calls MCP tools to create the workflow, the session, and the webhook destination live.
• Pin the V3 contract. Every example in this page uses plural-array decision keys. Treat the singular V2 fields as deprecated — only enable them by creating a separate destination with webhook_version: "V2" if a downstream consumer cannot migrate.
• Cross-reference. Pair this page with Data models (per-feature schema), Verification statuses (literal status strings), and Webhooks (signature verification and retry policy).