> ## 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. # Prompt de integración para los tres productos de Didit > Un prompt reutilizable de Didit para verificación de identidad, monitorización de transacciones y autenticación, unidos por una referencia de persona estable. Usa un solo prompt para integrar **Verificación de identidad**, **Monitoreo de transacciones**, **Autenticación** o cualquier combinación de ellos. Selecciona los productos en el bloque de contexto de la aplicación; tu agente implementa solo esos flujos.> [!WARNING] > > Autenticación es nueva. Su flujo alojado, el emisor de JWT ES256, los eventos de autenticación y la protección contra bots están documentados; sus paquetes de SDK aún no están publicados. El prompt exige que el agente compruebe la disponibilidad y mantenga desactivados los adaptadores no compatibles. No debe inventar un SDK funcional ni afirmar que una integración no disponible ha superado las pruebas.## Usar el prompt1) Haz clic en **Copiar** y pega el prompt en tu agente de programación. 2) Indica tu stack, tu plataforma, los productos seleccionados y la configuración actual de tu aplicación. 3) Elige un identificador estable para la persona en `vendor_data`. Tu backend lo obtiene a partir del usuario autenticado. 4) Revisa la implementación generada y los resultados de sus pruebas antes de activarla para tus clientes. Prompt de integración de Didit Copiar el prompt al portapapeles \

\````# Integrate Didit into my application

Integrate the Didit products I select into my application. Identity verification checks people, Transaction monitoring evaluates transactions and application events, and Authentication signs end users into my app. Each product can be used alone. Keep their credentials and decisions separate while linking the same person through vendor_data.

\## My application context

\
Stack: [framework + language - e.g. Next.js 15 + TypeScript, Django, Rails, Go]
Surface: [web | iOS | Android | React Native | Flutter | backend-only]
Products: [Identity verification | Transaction monitoring | Authentication; choose any combination]
Existing Didit application: [configured environment, or needs setup]
Person reference: [stable server-owned identifier used as vendor_data]
Use case: [KYC at signup | KYB at business onboarding | age gate | re-auth | transaction monitoring | other]
Database: [Postgres | MySQL | Mongo | other]
\

\## Choose the products first

Build only the products selected in my application context. Use one stable, server-owned person reference across products. Do not add verification screens, transaction submissions or sign-in requirements for an unselected product.

\| Products | Sections to implement |
\| --- | --- |
\| Identity verification | Identity verification (steps 2-7) |
\| Transaction monitoring | Transaction monitoring |
\| Authentication | Authentication |
\| Identity verification + Transaction monitoring | Both selected sections |
\| Identity verification + Authentication | Both selected sections |
\| Transaction monitoring + Authentication | Both selected sections |
\| Identity verification + Transaction monitoring + Authentication | All three sections |

Authentication is new, and the @didit-protocol/auth* and @didit-protocol/signals packages are not published yet. Use the documented hosted flow and issuer for Authentication. First inspect the installed/published versions and the application's enabled capabilities. If a dependency is unavailable, keep that integration disabled, explain the missing capability, and complete the independently available products. Never invent an SDK export, issuer URL, webhook type, package version or working result. Do not call a release-dependent integration complete.

Use the same Didit application/environment for the selected products. Resolve vendor_data from the authenticated user on my server. Never trust a browser-supplied user identifier when creating a verification session or minting a scoped token. Sandbox and live identities are separate.

Authentication puts the person's vendor_data in the access token, the ID token and GET session/: the external_id supplied at import, otherwise the Didit identity ID. Read it from a verified token on my server and reuse it for verification sessions and transactions. Never link people solely by an unverified email or generate a new vendor_data for each product.

Credential boundaries:
\- x-api-key: server-side verification/monitoring API credential.
\- X-Transaction-Token: short-lived transaction credential scoped to vendor_data, returned as sdk_token.
\- X-Monitoring-Token: short-lived event credential scoped to vendor_data, returned as monitoring_token.
\- End-user Bearer access token: Authentication runtime session; not a console token or verification API key.
\- Publishable key: identifies an application for the upcoming Authentication SDK; never grants server authorization.

Reuse my existing Didit account and application. Step 1 is optional account provisioning, not end-user signup. Use https://docs.didit.me/integration/programmatic-registration for the current console account flow; do not change its confirmation-code contract. If I select only Authentication, obtain an enabled application and copy its sign-in origin from the console; do not create an unused verification workflow or API key integration.

\## Step 1 - Create a developer account (only if needed)

Two API calls. No browser. No 2FA. Returns an `api_key` you use for every subsequent verification API request.

\```bash
\# 1) Register - creates a pending account + emails a 6-character code (10 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special (!@#$%^&*()_+-=[]{}|;:,.<>?)
\#    IMPORTANT: substitute "you@yourdomain.com" with a real inbox. Reserved test domains
\#    (@example.com, @example.org, @*.test, @*.example, @*.invalid) are refused by mail delivery and the call returns 500.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/   -H "Content-Type: application/json"   -d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'
\# 201 -> {"message": "Registration successful...", "email": "you@yourdomain.com"}

\# 2) Verify email with the code from the inbox - returns api_key, JWT tokens, org, app.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/   -H "Content-Type: application/json"   -d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> {
\#   "access_token": "...", "refresh_token": "...", "expires_in": 86400,
\#   "organization": { "uuid": "..." },
\#   "application":  { "uuid": "...", "client_id": "...", "api_key": "..." }
\# }
\# Persist response.application.api_key server-side; keep webhook secrets and other credentials separate.
\```

Persist the returned `api_key` as the env var `DIDIT_API_KEY`. Auth header for every verification API call:
\`x-api-key: $DIDIT_API_KEY`

If you lose the key, log in again with `POST /programmatic/login/` (same body as register) → `GET /organizations/me/` (gives org_id) → `GET /organizations/me/{org_id}/applications/` (lists apps; gives app_id) → `GET /organizations/me/{org_id}/applications/{app_id}/` and read `api_key` from the response. If your email verification code expired, request a fresh one with `POST /programmatic/resend-otp/` (email + password; 60s cooldown) or simply re-register (returns 200 with a new code).

\## Base URLs

\| Surface | Base URL |
\|---|---|
\| Verification API - every `/v3/...` endpoint (sessions, workflows, lists, billing, webhook destinations, entities, transactions, standalone APIs) | `https://verification.didit.me` |
\| Auth / account-management API (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `https://apx.didit.me` |
\| Console (human UI) | `https://business.didit.me` |
\| Hosted verification URL handed to end users | `https://verify.didit.me` |
\| Docs (cross-check anything) | `https://docs.didit.me` |
\| OpenAPI spec (verification API) | `https://docs.didit.me/openapi-25.json` |
\| OpenAPI spec (auth + apps) | `https://docs.didit.me/openapi-auth.json` |

\## Identity verification (steps 2-7, only when selected)

If Identity verification is not selected, skip to the selected product section below.

\## Step 2 - Choose the verification approach

Pick exactly one, based on my use case:

\- **Approach A - Sessions API + SDK (recommended for any end-user verification flow).** My backend creates a Didit session → my frontend opens the Didit-hosted verification UI (via SDK / iframe / redirect) → user completes verification → my backend receives a webhook with the decision. Best for KYC at signup, KYB at business onboarding, age verification, re-auth. Didit-hosted flows are A/B-tested and convert higher than custom UIs.
\- **Approach B - Standalone APIs (server-to-server only).** My backend calls individual modules directly (`/v3/id-verification/`, `/v3/aml/`, `/v3/face-match/`, etc.) for batch jobs or fully custom UI. Best for back-office verification pipelines.

If unsure, default to Approach A.

\## Step 3 - Create or reuse a workflow

A workflow defines which modules run during a session and the per-feature thresholds. Create one via API (or `https://business.didit.me` → Workflows → Create).

\```bash
\# List existing workflows (newest first; paginated envelope {count, next, previous, results}, page size 50).
curl https://verification.didit.me/v3/workflows/   -H "x-api-key: $DIDIT_API_KEY"

\# Create a new KYC workflow.
\# - workflow_label and features are REQUIRED; the v3 API rejects any unknown
\#   body field with 400 (there is NO workflow_type field - see KYB note below).
\# - features[] entries are objects: { "feature": "", "config": { ... } }
\# - The config block is optional per feature; sensible defaults apply.
\# - Defaults to a published v1 workflow, ready for sessions. Not idempotent -
\#   each call creates a new workflow.
curl -X POST https://verification.didit.me/v3/workflows/   -H "x-api-key: $DIDIT_API_KEY"   -H "Content-Type: application/json"   -d '{
    "workflow_label": "Standard KYC",
    "features": [
      \{ "feature": "OCR" },
      \{ "feature": "LIVENESS", "config": { "face_liveness_method": "PASSIVE" } },
      \{ "feature": "FACE_MATCH" },
      \{ "feature": "IP_ANALYSIS" }
    ]
  }'
\# 201 -> the full workflow record. Save response.workflow_id (also exposed as
\# response.uuid) as DIDIT_WORKFLOW_ID - it's what you pass to POST /v3/session/.
\```

Feature enum values (UPPERCASE, source: `management-api/workflows/feature-configs.mdx`):
\- **KYC features:** `OCR`, `NFC`, `LIVENESS` (`face_liveness_method`: `PASSIVE` | `ACTIVE_3D` | `FLASHING`), `FACE_MATCH`, `AGE_ESTIMATION`, `PHONE_VERIFICATION`, `EMAIL_VERIFICATION`, `DATABASE_VALIDATION`, `AML`, `IP_ANALYSIS`, `PROOF_OF_ADDRESS`, `QUESTIONNAIRE`.
\- **KYB features:** `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE` (each plus `AML` / `DATABASE_VALIDATION` as needed).

There is **no** `workflow_type` request field - including any KYB feature (`KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`) automatically makes the workflow KYB; sending `workflow_type` (or any other unknown field) returns 400. Keep KYC and KYB as separate workflows.

\## Step 4 - Install the SDK that matches my stack

\| Stack | Package | Install |
\|---|---|---|
\| Web (React, Vue, Next.js, Nuxt, Svelte, vanilla JS) | `@didit-protocol/sdk-web` | `npm install @didit-protocol/sdk-web` |
\| iOS (Swift / SwiftUI) | `sdk-ios` | SPM: `https://github.com/didit-protocol/sdk-ios` |
\| Android (Kotlin / Jetpack Compose) | `me.didit:didit-sdk` | Custom Maven repository; see https://docs.didit.me/integration/native-sdks/android-sdk |
\| React Native (Expo or bare) | `@didit-protocol/sdk-react-native` | `npm install @didit-protocol/sdk-react-native` |
\| Flutter | `didit_sdk` | `flutter pub add didit_sdk` |
\| Backend-only / batch / custom UI | none - call REST directly | - |

Always prefer native iOS / Android SDKs over WebView on mobile (NFC + camera + biometrics work natively).

\## Step 5 - Create a session and present it to the user

\**Backend creates the session:**

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

Successful response (201 Created - always exactly these 10 keys):
\```json
\{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "session_token": "3FaJ9wLqX2Mz",
  "url": "https://verify.didit.me/session/3FaJ9wLqX2Mz",
  "vendor_data": "internal-user-id",
  "metadata": null,
  "status": "Not Started",
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "workflow_version": 3,
  "callback": "https://myapp.com/done"
}
\```

\- `session_token` is a **12-character URL-safe token** (not a JWT) embedded in `url`. Treat it as a secret - anyone holding it can open this session's verification flow.
\- After the user finishes, Didit redirects to `callback` with `?verificationSessionId={session_id}&status={status}` appended.
\- **Idempotent reuse:** if an unfinished session (`Not Started` / `In Progress` / `Resubmitted` / `Awaiting User`) with the same `vendor_data` already exists on the workflow's latest published version, that session is returned (still `201`) with its `callback` and `metadata` updated to the new values - retrying never creates duplicates. Finished sessions (`Approved`, `Declined`, `In Review`, `Expired`, `Abandoned`, `Kyc Expired`) are never reused.

\`vendor_data` is **my internal user ID** - Didit links the session to a User entity (auto-created if new). For KYB workflows it links to a Business entity.

\**Optional create-session fields:**

\| Field | Type | Notes |
\|---|---|---|
\| `callback_method` | `"initiator"` \\| `"completer"` \\| `"both"` | Which side of a cross-device flow receives the `callback` redirect. Default `"initiator"`; set `"both"` if the callback isn't triggering reliably. |
\| `metadata` | object | Arbitrary JSON; echoed back on every webhook for this session. |
\| `language` | ISO 639-1 string | Locks the hosted UI to that language (defaults to browser detection). When set, the returned `url` gains a language path segment: `https://verify.didit.me/{language}/session/{session_token}`. |
\| `contact_details` | `{ email, send_notification_emails, email_lang, phone }` | Lets Didit email the user the hosted-flow link and prefill email/phone verification steps. `phone` must be E.164. `phone` is ignored for KYB workflows. |
\| `expected_details` | KYC: `{ first_name, last_name, date_of_birth, gender, nationality, country, id_country, poa_country, address, identification_number, ip_address, expected_document_types }` - KYB: `{ company_name, registry_country, registration_number }` | KYC: cross-validates extracted document data against what your app already knows (mismatches surface as warnings). `expected_document_types` restricts which documents the user may present - codes: `P`, `ID`, `DL`, `RP`, `HIC`, `TC`, `SSC`. `address` requires `country` or `poa_country`, else 400. KYB: the business fields pre-fill the hosted company search (locked country, editable name and number fields) and the asserted search runs automatically, combining both identifiers when both are set - prefill only, no mismatch warnings. `registry_country` is `XX` or `XX-YY` for state-level registries (e.g. `US-CA`). Person-level fields are ignored for KYB. |
\| `portrait_image` | base64 string | Reference face (max 2MB; JPEG/PNG/WebP/TIFF). Required only for Biometric Authentication / Face-Match-first workflows; ignored otherwise. |
\| `sandbox_scenario` | string | Sandbox apps only (e.g. `"approve"`, `"decline_aml_hit"`) - auto-populates magic inputs to force that outcome. 400 on live apps. |

\**Auth failure shape.** On the session, workflow, and standalone-API endpoints, a missing, malformed, expired, or wrong-app `x-api-key` always returns **HTTP 403** (never 401) with body:
\```json
\{ "detail": "You do not have permission to perform this action." }
\```
There is no machine-readable discriminator - handle missing/expired/wrong-app cases uniformly by re-checking your env var or rotating the key in the console. (Exception: the management families - `/v3/users/`, `/v3/businesses/`, `/v3/transactions/`, `/v3/billing/`, `/v3/webhook/destinations/` - return **401** for a missing/malformed key and reserve **403** for a valid key lacking permission. Treat any 401/403 as "fix the key".)

\**Frontend presents the verification (pick one):**

\| Pattern | Code |
\|---|---|
\| Web JS SDK (modal) | `import { DiditSdk } from "@didit-protocol/sdk-web"; DiditSdk.shared.startVerification({ url })` |
\| Iframe (embedded) | `