@didit-protocol/mcp-server 5.1.36 → 5.1.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +131 -29
  2. package/dist/app-api-key.d.ts +5 -0
  3. package/dist/app-api-key.d.ts.map +1 -0
  4. package/dist/app-api-key.js +108 -0
  5. package/dist/app-api-key.js.map +1 -0
  6. package/dist/auth/cached-verifier.d.ts +38 -0
  7. package/dist/auth/cached-verifier.d.ts.map +1 -0
  8. package/dist/auth/cached-verifier.js +82 -0
  9. package/dist/auth/cached-verifier.js.map +1 -0
  10. package/dist/auth/introspection-verifier.d.ts +12 -0
  11. package/dist/auth/introspection-verifier.d.ts.map +1 -1
  12. package/dist/auth/introspection-verifier.js +40 -14
  13. package/dist/auth/introspection-verifier.js.map +1 -1
  14. package/dist/chatgpt-app.d.ts +1 -0
  15. package/dist/chatgpt-app.d.ts.map +1 -1
  16. package/dist/chatgpt-app.js +2 -0
  17. package/dist/chatgpt-app.js.map +1 -1
  18. package/dist/config.d.ts +8 -3
  19. package/dist/config.d.ts.map +1 -1
  20. package/dist/config.js +24 -7
  21. package/dist/config.js.map +1 -1
  22. package/dist/http.d.ts.map +1 -1
  23. package/dist/http.js +43 -1
  24. package/dist/http.js.map +1 -1
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +294 -33
  27. package/dist/index.js.map +1 -1
  28. package/dist/investigator-agent.d.ts +4 -0
  29. package/dist/investigator-agent.d.ts.map +1 -0
  30. package/dist/investigator-agent.js +10 -0
  31. package/dist/investigator-agent.js.map +1 -0
  32. package/dist/permissions.d.ts.map +1 -1
  33. package/dist/permissions.js +18 -3
  34. package/dist/permissions.js.map +1 -1
  35. package/dist/schema/feature-config-schema.json +941 -28
  36. package/dist/security.js +2 -2
  37. package/dist/security.js.map +1 -1
  38. package/dist/signature-download.d.ts +31 -0
  39. package/dist/signature-download.d.ts.map +1 -0
  40. package/dist/signature-download.js +122 -0
  41. package/dist/signature-download.js.map +1 -0
  42. package/dist/tools/billing.d.ts +1 -0
  43. package/dist/tools/billing.d.ts.map +1 -1
  44. package/dist/tools/billing.js +5 -3
  45. package/dist/tools/billing.js.map +1 -1
  46. package/dist/tools/compliance.d.ts.map +1 -1
  47. package/dist/tools/compliance.js +37 -0
  48. package/dist/tools/compliance.js.map +1 -1
  49. package/dist/tools/investigator.d.ts +19 -0
  50. package/dist/tools/investigator.d.ts.map +1 -0
  51. package/dist/tools/investigator.js +449 -0
  52. package/dist/tools/investigator.js.map +1 -0
  53. package/dist/tools/observability.d.ts +6 -0
  54. package/dist/tools/observability.d.ts.map +1 -1
  55. package/dist/tools/observability.js +11 -3
  56. package/dist/tools/observability.js.map +1 -1
  57. package/dist/tools/search.d.ts.map +1 -1
  58. package/dist/tools/search.js +89 -5
  59. package/dist/tools/search.js.map +1 -1
  60. package/dist/tools/session-explain-levers.d.ts +6 -0
  61. package/dist/tools/session-explain-levers.d.ts.map +1 -1
  62. package/dist/tools/session-explain-levers.js +40 -7
  63. package/dist/tools/session-explain-levers.js.map +1 -1
  64. package/dist/tools/sessions.d.ts +18 -0
  65. package/dist/tools/sessions.d.ts.map +1 -1
  66. package/dist/tools/sessions.js +155 -2
  67. package/dist/tools/sessions.js.map +1 -1
  68. package/dist/tools/standalone.d.ts +5 -0
  69. package/dist/tools/standalone.d.ts.map +1 -1
  70. package/dist/tools/standalone.js +18 -2
  71. package/dist/tools/standalone.js.map +1 -1
  72. package/package.json +1 -1
package/README.md CHANGED
@@ -26,6 +26,16 @@ key protects the credentials embedded in the session-scoped link; rotating it
26
26
  invalidates outstanding links. Treat links as secrets and redact the `token` query
27
27
  parameter in proxy/access logs. Responses use `Cache-Control: no-store`.
28
28
 
29
+ ### E-signature files
30
+
31
+ `didit_session_get_signature_evidence`, `didit_session_get_signed_document` and
32
+ `didit_session_get_signature_field_image` return the same kind of link (plus `content_type`)
33
+ for a signer's evidence PDF, the signed PDF of one document and the PNG of a signature field.
34
+ They use the same `MCP_PDF_DOWNLOAD_KEY` and `MCP_RESOURCE_URI`; route
35
+ `/downloads/session-signature` to this HTTP server as well. The file is checked against its
36
+ recorded SHA-256 at issuance and again at download. `didit_session_validate_signatures`
37
+ re-validates the signed documents and returns the result as JSON.
38
+
29
39
  Stdio deployments need a reachable HTTP deployment with the same key, API base URL,
30
40
  and `MCP_RESOURCE_URI`; stdio alone cannot serve download links. Missing key
31
41
  configuration produces an actionable tool error instead of inline PDF data.
@@ -67,6 +77,8 @@ The MCP is an OAuth 2.1 **resource server**; the Didit console (`business.didit.
67
77
  Scopes: `didit:management` (workspace operations), `didit:verification` (running checks) and `didit:staff` (Didit staff accounts only; the authorization server never issues it to anyone else). Your console **role** is enforced server-side on every call.
68
78
 
69
79
  > **There is no API-key mode.** Every tool targets the user-scoped console endpoints (`/organization/{org}/application/{app}/…`), which authorize a Bearer token with per-role privileges and reject `x-api-key`. (For raw REST access with an application API key — e.g. creating sessions from your backend — use the [REST API](https://docs.didit.me) directly, not this server.)
80
+ >
81
+ > The one exception is the phone code pair, `didit_verify_phone_send` and `didit_verify_phone_check`: the console has no route for them, so the MCP reads the application's API key with your sign-in (a role with `create:sessions` and the `didit:management` scope, or an organization owner or admin for a local `didit_account_login` token) and calls the public phone API with it. The key is never returned, stored or logged.
70
82
 
71
83
  See [Authentication](https://docs.didit.me/integration/mcp/authentication).
72
84
 
@@ -75,9 +87,10 @@ See [Authentication](https://docs.didit.me/integration/mcp/authentication).
75
87
  140+ tools, grouped by area. The full catalogue with read/write/destructive markers is in [`docs/TOOLS.md`](docs/TOOLS.md) and at [docs.didit.me](https://docs.didit.me/integration/mcp/tools). Highlights:
76
88
 
77
89
  - **Discovery & cross-app:** `didit_context_get`, `didit_session_search`, `didit_transaction_search`, `didit_vendor_user_search`, `didit_analytics` — aggregate across every org/app in one call.
78
- - **Sessions:** create, list, get decision, update status, reviews, bulk import, webhook delivery log + resend (`didit_session_webhooks` waits for a sandbox session's webhook so an integration can be verified end to end).
90
+ - **Sessions:** create, list, get decision, update status, reviews, bulk import, webhook delivery log + resend (`didit_session_webhooks` waits for a sandbox session's webhook so an integration can be verified end to end), Precise Location evidence (`didit_session_get_location_evidence`: every attempt and the same person's earlier checks behind a Location verdict).
79
91
  - **Verification APIs:** `didit_verify_id`, `didit_verify_aml`, `didit_verify_face_match`, `didit_verify_kyb_search`, …
80
92
  - **Workflows (incl. branching graphs):** `didit_workflow_search`, `didit_workflow_get_graph`, `didit_workflow_edit_graph` — build conditional/branching workflows (fuzzy-match conditions, Document-AI steps) by sending small ops; large feature configs are kept server-side, never resent. `didit_workflow_get_id_verification_methods_catalog` and `didit_workflow_get_kyb_registry_catalog` answer the server-driven questions a config write depends on (which countries offer non-doc lookup / wallets, which KYB data tiers and monitoring a country's registries sell).
93
+ - **Investigator (AI case reviewer):** `didit_investigator_queue_list`, `didit_investigator_report_get` (recommendation, basis, evidence, precedents), `didit_investigator_record_get` (the review of one verification or transaction, open or decided), `didit_investigator_add_note` (a fact the user adds, as a team note the next review reads), questions, the free backtest (`didit_investigator_backtest_start`), performance, dashboard and Activity. Its decisions (`didit_investigator_accept`, `_override`, `_batch_accept`), policy answers (`_question_answer`, `_question_dismiss`) and the re-review that replaces the open report (`_rereview`, optionally with a note) are annotated destructive and refused without `confirm: true`, which a client sends only after the user approves that exact action. Every Investigator call sends `X-Didit-Actor-Via: mcp` (or `copilot` when the console assistant marks its request so), so the Investigator Activity shows where the user acted from.
81
94
  - **Compliance:** transaction monitoring, custom and preset rule management with backtesting, lists/blocklist/allowlist, cases, reports, audit logs, alerts.
82
95
  - **Workspace:** questionnaires, webhooks, members, billing, branding.
83
96
 
@@ -119,7 +132,7 @@ A key that is not listed here is not part of the contract and is dropped silentl
119
132
 
120
133
  <!-- BEGIN GENERATED FEATURE CONFIG REFERENCE -->
121
134
 
122
- _Generated from `schema/feature-config-schema.json` (contract `sha256:a2c413a50107faf3ea47fa187089a930ac17d3d04893e24176f494a58470e982`, schema version 1), which is a copy of the artifact `service-didit-verification` generates from its feature-config serializers. Do not edit by hand — run `npm run schema:readme`._
135
+ _Generated from `schema/feature-config-schema.json` (contract `sha256:b5ff2371c2a41779d8421cf1333fd50706cb78f9eaa320656b0c30bdb7875226`, schema version 1), which is a copy of the artifact `service-didit-verification` generates from its feature-config serializers. Do not edit by hand — run `npm run schema:readme`._
123
136
 
124
137
  ### AGE_ESTIMATION
125
138
 
@@ -132,6 +145,7 @@ Configuration for Age Estimation feature.
132
145
  | `enable_id_verification_fallback` | boolean \| null | boolean | |
133
146
  | `external_capture_device_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an external capture device is detected. |
134
147
  | `face_audio_recording_enabled` | boolean \| null | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default. |
148
+ | `face_liveness_attack_face_match_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the liveness face matches (above the duplicate-face similarity bar) a face from an earlier session of this application whose own capture the liveness engine judged an attack (risk FACE_MATCHES_LIVENESS_ATTACK), another user's session only and only a confident attack verdict. Review or no action only - a decline set here is downgraded to review, because a genuine user can be rejected once by mistake and then pass. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
135
149
  | `face_liveness_duplicated_face_document_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a duplicate face is found on a user verified with a different date of birth. Another document of the same person (a passport after an identity card, a renewal, a document of a second country) is not flagged. |
136
150
  | `face_liveness_duplicated_face_name_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a duplicate face is found under a different name. |
137
151
  | `face_liveness_flash_mode` | string \| null | string | |
@@ -166,7 +180,7 @@ Configuration for AML feature (used for both KYC AML and KYB Company AML).
166
180
  | `aml_country_weight` | integer \| null | integer >=0 <=100 | |
167
181
  | `aml_dob_weight` | integer \| null | integer >=0 <=100 | |
168
182
  | `aml_entity_type` | string \| null | 'company'\|'person' | Whether this node screens a `person` or a `company`. Defaults to `person` on a person (KYC) workflow and to `company` on a business (KYB) workflow. Set it to `company` to screen the business named in an uploaded document (via `aml_field_sources`) without a KYB Registry step - the provider searches company records instead of people, and the match score is scored as a company. |
169
- | `aml_field_sources` | json \| null | {"full_name"\|"date_of_birth"\|"nationality"\|"document_number": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | Where this node reads the entity it screens, when the workflow has no ID Verification or KYB Registry step to supply it - a Document AI workflow over non-standardised documents (a tax certificate, an acta constitutiva). Same contract as `database_validation_field_sources`: `source` names the producer and `key` names the value inside it - a Document AI field key for `document_ai`, a questionnaire node id for `questionnaire`, and `expected_details.<field>` or `metadata.<key>` for `expected_data`. The map's KEY is one of the four AML screening inputs: `full_name`, `date_of_birth`, `nationality`, `document_number` - read for a company as legal name, incorporation date, country and registration number. A Document AI field already keyed as one of those four maps automatically and is deliberately not persisted, so renaming it never freezes a stale mapping. An explicit mapping wins over both the auto-map and the ID document, and a mapping that resolves to nothing at runtime leaves the input empty rather than falling back. With no ID Verification and no KYB Registry upstream, `full_name` must be fillable or the graph is rejected on save: there is no search without a name. |
183
+ | `aml_field_sources` | json \| null | {"full_name"\|"date_of_birth"\|"nationality"\|"document_number": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | Where this node reads the entity it screens, when the workflow has no ID Verification or KYB Registry step to supply it - a Document AI workflow over non-standardised documents (a tax certificate, an acta constitutiva). Same contract as `database_validation_field_sources`: `source` names the producer and `key` names the value inside it - a Document AI field key for `document_ai`, a questionnaire node id for `questionnaire`, and `expected_details.<field>` or `metadata.<key>` for `expected_data`. The map's KEY is one of the four AML screening inputs: `full_name`, `date_of_birth`, `nationality`, `document_number` - read for a company as legal name, incorporation date, country and registration number. A Document AI field already keyed as one of those four maps automatically and is deliberately not persisted, so renaming it never freezes a stale mapping. An explicit mapping wins over both the auto-map and the ID document, and a mapping that resolves to nothing at runtime leaves that input empty rather than falling back. The screened name is the exception on a person node: when the ID Verification step already named the person, that name stands in rather than leaving the node with no search to run. With no ID Verification and no KYB Registry upstream, `full_name` must be fillable or the graph is rejected on save: there is no search without a name. |
170
184
  | `aml_incomplete_data_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the screening ran on less than a full identity (name, date of birth and country). `REVIEW` is the default and the historical behaviour; `NO_ACTION` proceeds on reduced data for a workflow that knowingly holds only a name. The screening still runs either way, and the partial-data log is still recorded - this only decides what it does to the status. |
171
185
  | `aml_match_score_threshold` | integer \| null | integer >=0 <=100 | |
172
186
  | `aml_name_weight` | integer \| null | integer >=0 <=100 | |
@@ -193,40 +207,74 @@ Configuration for Bank Verification feature.
193
207
 
194
208
  | Key | Type | Accepts | Meaning |
195
209
  | --- | --- | --- | --- |
210
+ | `bank_abandoned_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the step ends without a match after the person left at their bank and never came back (an attempt timed out). |
211
+ | `bank_account_age_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the account is newer than `bank_account_age_days`, a common mule pattern. |
212
+ | `bank_account_age_days` | integer \| null | integer >=1 <=365 | An account whose history starts later than this many days ago counts as new, 1 to 365, defaulting to 30. Read from the transaction history, so only with the `transactions` scope. |
213
+ | `bank_account_check_accept_close_match` | boolean \| null | boolean | Account check only. On (the default), a name the bank scores between `bank_partial_match_floor` and `bank_name_match_threshold` is a close match: the person confirms the name the bank holds when `bank_suggest_holder_name` is on, and `bank_partial_match_action` decides. Off, that close match is a no match (`OWNER_NAME_MISMATCH`, decided by `bank_no_match_action`) and spends the attempt. Bank sign-in keeps its close matches either way. |
214
+ | `bank_account_check_max_attempts` | integer \| null | integer >=1 <=5 | How many account checks the user gets, 1 to 5 (3 when unset): how many times the person can type the account details for a check the bank answers. A separate count from `bank_max_attempts`. A check refused as typed (an invalid IBAN) or one the provider could not answer spends none. |
215
+ | `bank_account_lookup_enabled` | boolean \| null | boolean | Retired: use `bank_method_order` and `bank_countries.<ISO3>.methods`. Read for one release from a save that sends no `bank_method_order` (with `bank_open_banking_enabled`, it sets the order: the account check after bank sign-in when on; off when unset), and written back on every save as whether any country offers the account check. |
196
216
  | `bank_account_selection` | string \| null | 'auto'\|'user' | Whether the user picks which of the connected accounts is verified (`user`) or the first eligible one is taken (`auto`). |
197
- | `bank_allow_skip` | boolean \| null | boolean | Let the user skip the step instead of connecting a bank. A skip is then decided by `bank_skipped_action`. |
198
- | `bank_attempts_exhausted_action` | string \| null | 'REVIEW'\|'DECLINE' | Verdict when the user spent `bank_max_attempts` without a successful connection. |
217
+ | `bank_account_type_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the verified account is a savings account. |
218
+ | `bank_address_match_threshold` | integer \| null | integer >=50 <=100 | At or above this score the holder's address matches, 50 to 100, defaulting to 70. Only read with `bank_require_address_match`. |
219
+ | `bank_address_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder's address differs, which turns a match into a close match. Only with `bank_require_address_match`. |
220
+ | `bank_allow_skip` | boolean \| null | boolean | Retired by `bank_continue_without_bank`: still accepted, and written back from it on every save. A save that sends only this key gets `from_start` for `true` and `when_needed` otherwise. The person can always continue without a bank now. |
221
+ | `bank_attempts_exhausted_action` | string \| null | 'REVIEW'\|'DECLINE' | Verdict when the user spent the attempts of every method the country offers (`bank_max_attempts`, and `bank_account_check_max_attempts` where it offers the account check) without a successful connection, also when they then continue without a bank. |
222
+ | `bank_auto_add_countries` | boolean \| null | boolean | Offer every country a route of this node can serve, also the ones added after the node was saved, apart from countries `bank_countries` turns off. Off when the key is absent, so an existing node never widens on its own. |
199
223
  | `bank_business_account_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the institution types the holder as a business rather than a person. |
224
+ | `bank_cash_flow_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when money comes in and straight back out, or many small transfers come in (pass-through cash flow). Needs the `transactions` scope. |
200
225
  | `bank_connection_timeout_minutes` | integer \| null | integer >=5 <=60 | How long a started connection stays open before the attempt is abandoned, 5 to 60 minutes. |
201
226
  | `bank_consent_expired_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the bank consent lapses after the step was already decided. Only meaningful with `bank_refresh_enabled`. |
202
- | `bank_countries` | json \| null | {"<ISO3>": {"enabled": true\|false, "institutions": ["<institution_id>", ...] \| "all"}} | Which countries a user may connect a bank in - a WHITELIST, so an empty map means the node offers nothing and runs nothing. `institutions` narrows the picker to specific provider institution ids; `"all"` offers every identity-capable bank in the country. Coverage belongs to the route the node selected in `provider_key`: a country the native route or the connected marketplace provider cannot establish account ownership in is REFUSED on save rather than dropped, because connecting to a bank that returns no holder identity spends an attempt and a charge to end at `not_verifiable`. |
227
+ | `bank_continue_without_bank` | string \| null | 'from_start'\|'when_needed' | When the bank step shows "Continue without your bank". `when_needed` (the default) shows it once no method works for the person's country or bank (also when their bank cannot be reached and no other bank sign-in or account check could verify them), or when they say they have no online banking. `from_start` also shows it on the first screen. It cannot be turned off: the person can always continue, and the session then follows `bank_unsupported_action` when nothing could verify their country or bank, `bank_attempts_exhausted_action` when every attempt is spent, and `bank_skipped_action` otherwise. A failed attempt that spends the last one does not wait for the person: the step ends on its own with `bank_attempts_exhausted_action`. Every save writes it. |
228
+ | `bank_countries` | json \| null | {"<ISO3>": {"enabled": true\|false, "institutions": ["<institution_id>", ...] \| "all", "popular_institutions"?: ["<institution_id>", ...], "hidden_institutions"?: ["<institution_id>", ...], "methods"?: ["open_banking"\|"account_lookup", ...]}} | Which countries a user may connect a bank in - a WHITELIST, so an empty map means the node offers nothing and runs nothing (unless `bank_auto_add_countries` is on), and a map whose countries are all off is refused. `institutions` narrows the picker to specific provider institution ids; `"all"` offers every identity-capable bank in the country. `hidden_institutions` leaves banks out of the suggestions and the search; with `bank_popular_mode: manual`, `popular_institutions` are the banks shown as popular, in order. A bank is never both hidden and popular. Coverage belongs to the route the node selected in `provider_key`: the native route (a registered native route with an approved price) or the connected marketplace provider. A country no route of the node can establish account ownership in is KEPT on save, because the step is never a dead end: it offers no bank sign-in or account check there, only its fallbacks (a statement upload where the node offers one, micro-deposits where a route sends them) and Continue without a bank (`bank_continue_without_bank`). A code that names no country Didit verifies is refused on save. A statement-only country is refused when the organization's contract does not price the statement upload. `methods` sets which of bank sign-in (`open_banking`) and the account check (`account_lookup`) the country offers and in what order, over the step's `bank_method_order`: the person starts on the first one and is offered the second as its backup. A country a route serves whose `methods` leave it nothing, and any country whose `methods` name a method no route of the node serves there, are refused on save. |
203
229
  | `bank_country_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the institution's country differs from the expected/document country. |
204
230
  | `bank_currency_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the account currency is not in `bank_expected_currencies`. |
231
+ | `bank_dob_match_enabled` | boolean \| null | boolean | Compare the holder's date of birth, where the bank shares one, with the verified one. A mismatch never changes the ownership result: it fires `bank_dob_mismatch_action`. On by default. |
232
+ | `bank_dob_match_threshold` | integer \| null | integer >=50 <=100 | At or above this score the date of birth matches, 50 to 100, defaulting to 70. A date is the same day or not, so it scores 100 or 0. |
233
+ | `bank_dob_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder's date of birth differs. Only with `bank_dob_match_enabled`. |
205
234
  | `bank_eligible_account_types` | array \| null | array | Which account types the user may pick. Credit cards, loans and investment accounts are never eligible - they do not establish ownership of a payment account. Defaults to current/checking. |
235
+ | `bank_email_match_enabled` | boolean \| null | boolean | Compare the email on file at the bank with the session's verified email. A mismatch fires `bank_email_mismatch_action`. Off by default. |
236
+ | `bank_email_match_threshold` | integer \| null | integer >=50 <=100 | At or above this score the email matches, 50 to 100, defaulting to 70. |
237
+ | `bank_email_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder's email differs. Only with `bank_email_match_enabled`. |
238
+ | `bank_evidence_retention_days` | integer \| null | integer >=30 <=1825 | Delete the bank evidence this many days after the verdict: 30, 90, 365 or 1825. Null keeps it with the session. Deleted: the holder details, the identity they were compared against, the account identifiers, the financial data and an uploaded statement; a connection still live is revoked. The verdict, scores and reason codes stay. Deleting the session deletes everything, whichever comes first. |
206
239
  | `bank_expected_currencies` | array \| null | array | ISO 4217 currencies the account is expected to be in. Empty means any; a mismatch is reported through `bank_currency_mismatch_action`. |
207
- | `bank_field_sources` | json \| null | {"full_name"\|"first_name"\|"last_name"\|"address": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | Where to read a reference-identity field when no earlier step in the graph can fill it. The map's KEY is one of `full_name`, `first_name`, `last_name`, `address`; `source` names the producer and `key` names the value inside it - a Document AI field key for `document_ai`, a questionnaire node id for `questionnaire`, and `expected_details.<field>` or `metadata.<key>` for `expected_data`. An `expected_details.<field>` VALUE may only name a field the session-create payload actually carries - `address`, `country`, `date_of_birth`, `first_name`, `gender`, `id_country`, `identification_number`, `ip_address`, `last_name`, `nationality` or `poa_country`. A malformed entry is refused on save, not dropped. |
240
+ | `bank_fallback_used_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the account was verified with micro-deposits or a statement upload. |
241
+ | `bank_field_sources` | json \| null | {"full_name"\|"first_name"\|"last_name"\|"address"\|"date_of_birth"\|"phone"\|"email": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | Where to read a reference-identity field when no earlier step in the graph can fill it. The map's KEY is one of `full_name`, `first_name`, `last_name`, `address`, `date_of_birth`, `phone`, `email`; `source` names the producer and `key` names the value inside it - a Document AI field key for `document_ai`, a questionnaire node id for `questionnaire`, and `expected_details.<field>` or `metadata.<key>` for `expected_data`. An `expected_details.<field>` VALUE may only name a field the session-create payload actually carries - `address`, `country`, `date_of_birth`, `first_name`, `gender`, `id_country`, `identification_number`, `ip_address`, `last_name`, `nationality` or `poa_country`. A malformed entry is refused on save, not dropped. |
208
242
  | `bank_joint_account_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the account has more than one holder. |
209
243
  | `bank_low_balance_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the available balance is below `bank_min_balance`. Needs the `balances` scope. |
210
- | `bank_max_attempts` | integer \| null | integer >=1 <=5 | How many connection attempts the user gets, 1 to 5. Spending them all without a successful connection is `bank_attempts_exhausted_action`. |
244
+ | `bank_match_any_holder` | boolean \| null | boolean | A joint or co-owned account matches when ANY listed holder matches the person. Off: only the first holder the bank lists can. On by default. |
245
+ | `bank_max_attempts` | integer \| null | integer >=1 <=5 | How many bank sign-in attempts the user gets, 1 to 5; a micro-deposit or statement fallback spends one too. The account check has its own `bank_account_check_max_attempts`. The step ends once every method the country offers has spent its attempts, which without a successful connection is `bank_attempts_exhausted_action`. |
246
+ | `bank_method_order` | array \| null | ["open_banking"\|"account_lookup", ...] | Which of the two methods the step offers and in what order, for every country that sets no `methods` of its own in `bank_countries`: `open_banking` is bank sign-in (the person signs in at their bank and shares the account holder, plus balances, transactions and income when the step asks for them), `account_lookup` is the account check (no sign-in: the person types the account details, an IBAN, a sort code and account number, a CLABE..., and the bank confirms the name on it; ownership only). In each country the person starts on the first method a route serves there, and is offered the other one as its backup under "Other ways to verify"; where a country offers both, the account check also stands in for a bank whose sign-in is degraded or down. A method no route serves in a country is left out there. At least one method; a save that names none gets `["open_banking", "account_lookup"]`, unless it sends `bank_open_banking_enabled` or `bank_account_lookup_enabled`, which then set it. The account check is billed once per check the provider answers (a match, a close match, a no match, an account it could not verify or did not find); an account refused before the check bills nothing. |
247
+ | `bank_microdeposits_enabled` | boolean \| null | boolean | Offer micro-deposits as a fallback: two small deposits reach the account and the person enters the amounts. Offered only in a country whose route can send them, after a charged bank verification attempt in the same session. Included at no extra charge; the customer pays the route price once. Sandbox sessions can test it without billing. The holder is the name the session verified, which the person declares the account is under, so a verified account records a `holder_declared` warning. On by default. |
211
248
  | `bank_min_balance` | number \| null | number >=0 | Minimum available balance, in the account's own currency. Below it `bank_low_balance_action` fires. Needs the `balances` scope and the save is refused without it. 0 is a real cutoff - it triggers the action for an overdrawn account - but the action defaults to `NO_ACTION`, so the verdict is unchanged unless another action is configured. This is not the same as leaving the key out. |
249
+ | `bank_mule_score_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the mule score is at or above `bank_mule_score_threshold`. |
250
+ | `bank_mule_score_threshold` | integer \| null | integer >=0 <=100 | At or above this mule score, 0 to 100, `bank_mule_score_action` fires; defaults to 70. The score combines a new account, pass-through cash flow, a drained balance and many small transfers in, read from the transaction history (the `transactions` scope). |
212
251
  | `bank_name_match_threshold` | integer \| null | integer >=50 <=100 | At or above this score the holder name is a match. 50 to 100, defaults to 85. |
213
252
  | `bank_no_match_action` | string \| null | 'REVIEW'\|'DECLINE' | Verdict when the account holder is demonstrably not the verified person (best name score below `bank_partial_match_floor`). |
214
253
  | `bank_not_verifiable_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the institution connected but returned no holder identity to compare. |
254
+ | `bank_open_banking_enabled` | boolean \| null | boolean | Retired: use `bank_method_order` and `bank_countries.<ISO3>.methods`. Read for one release from a save that sends no `bank_method_order` (with `bank_account_lookup_enabled`, it sets the order: bank sign-in when on, which is the default), and written back on every save as whether any country offers bank sign-in. |
215
255
  | `bank_partial_match_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder name lands between `bank_partial_match_floor` and `bank_name_match_threshold`. Never approves by default. |
216
- | `bank_partial_match_floor` | integer \| null | integer >=0 <=99 | Below this score the holder name is a no-match. 0 to 99, defaults to 70. The band between the floor and the threshold is the partial match, so the floor must be strictly below `bank_name_match_threshold` or the save is refused. An explicit null means "use the default" here too, which is why a threshold of 50 with no floor is refused: it is checked against the default floor of 70. |
217
- | `bank_reference_identity` | string \| null | 'auto'\|'database_validation'\|'expected_details'\|'kyc'\|'questionnaire' | Which earlier step supplies the identity the account holder is compared against: `kyc` (ID Verification), `database_validation`, `expected_details` (the session-create payload), `questionnaire`, or `auto` to use whichever one the workflow produced. The step that actually supplied it is recorded on the result as `reference_identity_source`. |
256
+ | `bank_partial_match_floor` | integer \| null | integer >=0 <=99 | The close-match value: below this score the holder name is a no-match. 0 to 99, defaults to 70. The band between the floor and the threshold is the partial match, so the floor must be strictly below `bank_name_match_threshold` or the save is refused. An explicit null means "use the default" here too, which is why a threshold of 50 with no floor is refused: it is checked against the default floor of 70. |
257
+ | `bank_phone_match_enabled` | boolean \| null | boolean | Compare the phone on file at the bank with the session's verified phone. A mismatch fires `bank_phone_mismatch_action`. Off by default. |
258
+ | `bank_phone_match_threshold` | integer \| null | integer >=50 <=100 | At or above this score the phone matches, 50 to 100, defaulting to 70. |
259
+ | `bank_phone_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder's phone differs. Only with `bank_phone_match_enabled`. |
260
+ | `bank_popular_mode` | string \| null | 'auto'\|'manual' | `auto` (the default) orders the popular banks by what people in the country connect most; `manual` shows each country's `popular_institutions` from `bank_countries` instead, in their order. |
261
+ | `bank_reference_identity` | string \| null | 'auto'\|'database_validation'\|'expected_details'\|'kyc'\|'questionnaire' | Which earlier step supplies the identity the account holder is compared against: `kyc` (ID Verification), `database_validation`, `expected_details` (the session-create payload), `questionnaire`, or `auto` to use whichever one the workflow produced. The step that actually supplied the compared name is recorded on the result as `reference_identity_source`: a name mapped in `bank_field_sources` records where it was mapped from (`document_ai` among them), and a business session records `kyb`. |
218
262
  | `bank_reference_identity_missing_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no earlier step produced an identity to compare the holder against, so ownership can only be `unknown`. |
219
263
  | `bank_refresh_enabled` | boolean \| null | boolean | Re-fetch the account's financial data after the step has already been decided, for as long as the bank consent lasts. Needs at least one of the `balances`, `transactions` or `income` scopes and the save is refused without one. A consent that lapses afterwards is `bank_consent_expired_action`. |
220
- | `bank_require_address_match` | boolean \| null | boolean | Also require the holder's address to match. A name that reached the threshold but whose address scores below it drops to a partial match. An institution that returns no address waives the requirement; a session with no address of its own to compare against does not, and lands on a partial match. Off by default. |
264
+ | `bank_require_address_match` | boolean \| null | boolean | Also require the holder's address to match. A name that reached the threshold but whose address scores below `bank_address_match_threshold` drops to a close match decided by `bank_address_mismatch_action`. An institution that returns no address waives the requirement; a session with no address of its own to compare against does not, and lands on a close match decided by `bank_partial_match_action`. Off by default. |
221
265
  | `bank_require_oauth_only` | boolean \| null | boolean | Offer only institutions reachable over OAuth / app-to-app, never a provider's legacy credential-capture surface. Where open banking already makes OAuth the only route, this changes nothing. |
222
- | `bank_scopes` | json \| null | {"ownership": true, "identifiers": true\|false, "balances": true\|false, "transactions": true\|false, "income": true\|false} | What the user is asked to consent to sharing. `ownership` is what the product verifies and cannot be turned off. `identifiers` unmasks the IBAN / account number; `balances`, `transactions` and `income` read real financial data, are each billed separately, and are refused on save unless the application carries the `bank_financial_data` entitlement. A scope that is off is never requested from the provider, so the bank never shows it on its consent screen. |
266
+ | `bank_scopes` | json \| null | {"ownership": true, "identifiers": true\|false, "balances": true\|false, "transactions": true\|false, "income": true\|false} | What the user is asked to consent to sharing. `ownership` is what the product verifies and cannot be turned off. `identifiers` unmasks the IBAN / account number; `balances`, `transactions` and `income` read real financial data, are each billed separately, and are refused on save unless the application carries the `bank_financial_data` entitlement. On a node that can run on Didit's own routes, each of them is also refused when a country the node offers has no route that reads it with bank sign-in: only bank sign-in reads data, so the data must come from the person's bank (the console offers only the scopes every country reads). A country that offers only the account check is not refused: a person who verifies by account check passes without the data, which the result lists in `financial_data.not_collected`. A scope that is off is never requested from the provider, so the bank never shows it on its consent screen. |
223
267
  | `bank_show_match_result_to_user` | boolean \| null | boolean | Show the ownership result to the user inside the verification flow. Off means it is recorded on the session but never shown to them. |
224
- | `bank_skipped_action` | string \| null | 'REVIEW'\|'DECLINE' | Verdict when the user skipped the step. Only reachable with `bank_allow_skip`. |
268
+ | `bank_skipped_action` | string \| null | 'REVIEW'\|'DECLINE' | Verdict when the person chose "Continue without your bank" while a way to verify was there. Defaults to `REVIEW`. The bank result then has `continued_without_bank` true and `SKIPPED` in its reason codes. |
269
+ | `bank_statement_document_checks_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an uploaded statement carries editing or tampering evidence. Defaults to `REVIEW`. |
270
+ | `bank_statement_enabled` | boolean \| null | boolean | Offer a bank statement upload as a fallback: a statement from the last 3 months, checked for tampering, whose holder name is matched like a bank's. Included at no extra charge after a charged bank verification attempt in the same session. With `bank_statement_standalone_enabled` it is also offered with no bank attempt before it, in any country. Sandbox sessions can test it without billing. Off by default. |
271
+ | `bank_statement_standalone_enabled` | boolean \| null | boolean | With `bank_statement_enabled`, also offer the statement upload when no bank attempt happened, in any country, including one no bank sign-in or account check route serves. Charged on its own as `bank_statement_upload`, USD 0.20 per evaluated statement at list price, with the organization's contract rate or special price applying as for any add-on; not offered where the contract does not price it. Sandbox sessions can test it without billing. On by default. |
225
272
  | `bank_store_full_identifiers` | boolean \| null | boolean | Store the account identifiers unmasked rather than masked. Needs the `identifiers` scope and the save is refused without it. Even then the unmasked form is only served to a caller holding the bank-verification read permission. |
226
273
  | `bank_store_raw_owner_data` | boolean \| null | boolean | Keep the holder details the institution returned next to the ownership evidence. Off means only the comparison itself is retained: scores, match method and reason codes. |
227
- | `bank_transactions_history_days` | integer \| null | integer >=30 <=365 | How far back transaction history is read, 30 to 365 days, defaulting to 90. Needs the `transactions` scope and the save is refused without it. |
274
+ | `bank_suggest_holder_name` | boolean \| null | boolean | On a close match, show the person the name the bank holds the account under and ask them to confirm it is theirs or to connect another account. Their answer is recorded as `holder_confirmation`; confirming ends the step on `bank_partial_match_action`. On by default. |
275
+ | `bank_transactions_history_days` | integer \| null | integer >=30 <=365 | How far back transaction history is read, 30 to 365 days, defaulting to 90. Needs the `transactions` scope and the save is refused without it. A node that may run on Didit's native route (no `provider_key`, or `fallback_to_native`) reads 30 or 90 days only: anything else is refused, because the native transactions add-on is priced for those two windows. |
228
276
  | `bank_unknown_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the evidence could not be fetched after retries - a transient failure. |
229
- | `bank_unsupported_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the user's bank is not supported and the node does not allow skipping. |
277
+ | `bank_unsupported_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the person continues without a bank because no method could verify their country or bank: no bank sign-in or account check route serves the country, or the bank they picked cannot be used on this step. Defaults to `REVIEW`. The bank result then has `continued_without_bank` true and `NOT_COVERED` in its reason codes. |
230
278
  | `bank_use_provider_score` | boolean \| null | boolean | Also read the institution's own holder-name score, and let it decide when it is higher than Didit's or when Didit had no holder name to score at all. A result decided that way reports `provider_only` as its match method, and a connection that returned no such score records a `provider_score_unavailable` warning. On by default. |
231
279
  | `fallback_to_native` | boolean \| null | boolean | Whether a marketplace connection that cannot be established falls back to Didit's native route. Off by default: a silent fallback would spend your Didit balance on a session you expected to run on your own provider contract. A fallback connection is recorded as `credential_source = native` and billed at the native price. |
232
280
  | `provider_key` | string \| null | string | Which route runs the step. Empty (the default) is Didit's native Bank Verification, a provider-independent product Didit routes to the regional open-banking vendor that serves the user's country and institution, on Didit's contracts and billing. A value names a MARKETPLACE provider whose own credentials this application has connected - the session then runs, is billed and is revoked on your provider account, and Didit charges only the marketplace platform fee. A provider that is not connected is refused on save. |
@@ -239,8 +287,8 @@ Configuration for Database Validation feature.
239
287
 
240
288
  | Key | Type | Accepts | Meaning |
241
289
  | --- | --- | --- | --- |
242
- | `database_validation_countries` | json \| null | {"<ISO3>": {"services": ["<service_id>", ...]}} | The databases to check, per country - this node runs NOTHING until at least one country carries at least one service id. Service ids come from the country's live catalog (e.g. `bra_cpf` for BRA); ids that do not belong to the named country, and countries with no live service, are dropped on save. The legacy `{"<ISO3>": "one_by_one"\|"two_by_two"\|"not_enabled"}` shape is still accepted and auto-expanded to that country's live services. |
243
- | `database_validation_field_sources` | json \| null | {"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | Where to read a database input that no earlier step in the graph can fill. `source` names the producer and `key` names the value inside it: a Document AI field key for `document_ai`, a questionnaire node id for `questionnaire`, and `expected_details.<field>` or `metadata.<key>` for `expected_data`. The two halves speak different vocabularies: the map's KEY is a Database Validation input field (`tax_id`, `document_number`, ...), while an `expected_details.<field>` VALUE may only name a field the session-create payload actually carries - `address`, `country`, `date_of_birth`, `first_name`, `gender`, `id_country`, `identification_number`, `ip_address`, `last_name`, `nationality` or `poa_country`. Anything else under `expected_details.` is rejected on save; `metadata.<key>` takes any non-empty whitespace-free customer key. Exact-key matches against an upstream step resolve automatically and are deliberately not persisted, so renaming a Document AI field never freezes a stale mapping into the config. A malformed entry is dropped on save rather than rejected, which un-satisfies its service and drops it from the selection. |
290
+ | `database_validation_countries` | json \| null | {"<ISO3>": {"services": ["<service_id>", ...]}} | The databases to check, per country - this node runs NOTHING until at least one country carries at least one service id. Service ids come from the country's live catalog (e.g. `bra_cpf` for BRA). An unknown id, an id that belongs to another country, and a service no workflow can run (not live yet, or offered only through the standalone `POST /v3/database-validation/`) are rejected with a 400 that names the service; a service the saved workflow already carries but can no longer run is removed on save. The legacy `{"<ISO3>": "one_by_one"\|"two_by_two"\|"not_enabled"}` shape is still accepted and auto-expanded to that country's live services. |
291
+ | `database_validation_field_sources` | json \| null | {"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<expected_details field>\|metadata.<key>"}} | Where to read a database input that no earlier step in the graph can fill. `source` names the producer and `key` names the value inside it: a Document AI field key for `document_ai`, a questionnaire node id for `questionnaire`, and `expected_details.<field>` or `metadata.<key>` for `expected_data`. The two halves speak different vocabularies: the map's KEY is a Database Validation input field (`tax_id`, `document_number`, ...), while an `expected_details.<field>` VALUE may only name a field the session-create payload actually carries - `address`, `country`, `date_of_birth`, `first_name`, `gender`, `id_country`, `identification_number`, `ip_address`, `last_name`, `nationality` or `poa_country`. Anything else under `expected_details.` is rejected on save; `metadata.<key>` takes any non-empty whitespace-free customer key. Exact-key matches against an upstream step resolve automatically and are deliberately not persisted, so renaming a Document AI field never freezes a stale mapping into the config. A malformed entry is rejected with a 400 that names its input field. |
244
292
  | `database_validation_no_match_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the database returns no match at all. |
245
293
  | `database_validation_not_applicable_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no selected database covers the holder's country or document. |
246
294
  | `database_validation_partial_match_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the database matches some, but not all, of the submitted fields. |
@@ -309,32 +357,48 @@ Configuration for the Precise Location (GEOLOCATION) feature. Every threshold is
309
357
 
310
358
  | Key | Type | Accepts | Meaning |
311
359
  | --- | --- | --- | --- |
312
- | `geolocation_accuracy_mode` | string \| null | 'approximate_allowed'\|'precise' | |
313
- | `geolocation_allow_qr_handoff` | boolean \| null | boolean | |
314
- | `geolocation_allow_skip` | boolean \| null | boolean | |
360
+ | `geolocation_accuracy_mode` | string \| null | 'approximate_allowed'\|'precise' | What the device is asked for. `precise` asks the operating system for a precise position, and a person who grants only an approximate one is asked again while attempts remain and then judged by `geolocation_approximate_action`; `approximate_allowed` accepts an approximate grant without that verdict. `geolocation_max_accuracy_radius_m` applies either way. `precise` when unset. |
361
+ | `geolocation_allow_qr_handoff` | boolean \| null | boolean | Offer to continue on a phone with a QR code while the step is still open (`allow_qr_handoff` in the step data, `can_handoff` on each submit answer). Native SDKs already run on the phone and never show the code. On by default. |
362
+ | `geolocation_allow_skip` | boolean \| null | boolean | Let the person go on without a location at any time, from the intro or a retry screen (`skipped: true`). The skip ends the step and is judged by `geolocation_unavailable_action`, except a skip that answers a refusal on a `continue_without_location` `geolocation_refusal_path`, which is recorded as that refusal. Off by default. |
315
363
  | `geolocation_approximate_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the user granted an approximate location while `geolocation_accuracy_mode` asks for a precise one. |
316
- | `geolocation_deep_link_enabled` | boolean \| null | boolean | |
364
+ | `geolocation_areas` | json \| null | [{"id": "<1-64 of A-Z a-z 0-9 _ ->", "label"?: "<text>", "type": "allowed"\|"blocked", "kind": "country", "country": "<ISO3>"} \| {..., "kind": "region", "country": "<ISO3>", "regions": ["<ISO 3166-2>", ...]} \| {..., "kind": "circle", "center": {"latitude": <num>, "longitude": <num>}, "radius_km": <1-500>} \| {..., "kind": "polygon", "points": [{"latitude": <num>, "longitude": <num>}, ...]}] | Allowed and blocked areas, applied while `is_geolocation_geofencing_enabled` is true. Only a position inside an allowed area passes, and a blocked area always wins over an allowed one. A position counts by its whole accuracy circle: a circle that crosses an edge that decides the answer is undetermined, never outside. A country or region ends where other land begins, never at its coastline, and a position the outlines place on no land (a seafront or pier the simplified coastline cut away) is undetermined for every country or region within its radius plus 12 nautical miles. `id` is what branch rules and `geolocation.inside_areas` / `geolocation.blocked_areas` name; `kind` picks the shape: a whole `country` (ISO 3166-1 alpha-3 with a published outline: a territory the outlines draw as another country's region is that `region`, such as Reunion as France's `FR-RE` or Bonaire, Sint Eustatius and Saba as `NL-BQ1` to `NL-BQ3`), `region` (ISO 3166-2 codes of one country with published boundaries), `circle` (1 to 500 km) or `polygon` (3 to 200 points, a ring whose edges never cross or touch each other). At most 50 areas, ids unique, and at least one allowed area while geofencing is on. Cannot be combined with `geolocation_geofencing_by_country`. |
365
+ | `geolocation_blocked_area_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the position, and its whole accuracy circle, falls inside a blocked area of `geolocation_areas`. Defaults to Decline. |
366
+ | `geolocation_consecutive_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when `geolocation_consecutive_mismatch_count` mismatches in a row are reached. Defaults to Review. |
367
+ | `geolocation_consecutive_mismatch_count` | integer \| null | integer | Raise LOCATION_CONSECUTIVE_MISMATCHES when this check and the same person's previous checks (same `vendor_data`) were outside the allowed areas, in a blocked area or too far from the address this many times in a row. A check that compared nothing neither extends nor breaks the streak, and neither does a position the device did not measure (a mocked or simulated fix, an emulator, a failed attestation). From 2 to 10; null (the default) is off. |
368
+ | `geolocation_deep_link_enabled` | boolean \| null | boolean | Forwarded to the client as `deep_link_enabled` in the step data: offer to open the customer's own app instead. The server applies no rule to it. Off by default. |
317
369
  | `geolocation_document_distance_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the device position is further from the document address than `geolocation_document_distance_km`. The address is geocoded coarsely, so this is a weak signal. |
318
- | `geolocation_document_distance_km` | integer \| null | integer >=0 | |
370
+ | `geolocation_document_distance_basis` | string \| null | 'declared'\|'document'\|'proof_of_address' | Which address `geolocation_document_distance_km` is measured from: `document` (the default: the identity document's address, then the proof of address), `proof_of_address` only, or `declared` (the `expected_details.address` given at session creation, geocoded). |
371
+ | `geolocation_document_distance_km` | integer \| null | integer >=0 | How far, in kilometres, the position (the IP location on an `ip_only` node) may be from the address `geolocation_document_distance_basis` names before `geolocation_document_distance_action` applies. Unset or null (the default) is off. |
319
372
  | `geolocation_document_distance_unit` | string \| null | 'imperial'\|'metric' | The unit the console shows `geolocation_document_distance_km` in. Display only: the stored value is always kilometres and no rule depends on it. |
373
+ | `geolocation_emulator_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the app that shared the location reported running on an emulator. Browsers cannot report it. Unless it is No action, it ends the step on that attempt: checking again cannot change the device. No action unless set or a preset says otherwise. |
320
374
  | `geolocation_geofence_undetermined_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the position cannot be placed inside or outside the fence because its accuracy circle reaches the boundary. Uncertainty is never reported as being outside. |
321
375
  | `geolocation_geofencing_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the device position, and its whole uncertainty circle, falls outside `geolocation_geofencing_by_country`. |
322
376
  | `geolocation_geofencing_by_country` | json \| null | {"<ISO3>": {"allowed": true\|false, "states"?: {"<ISO 3166-2 code>": {"allowed": true\|false}} \| null}} | Country and region allow/deny rules for the device's own position, applied only while `is_geolocation_geofencing_enabled` is true. Same shape as IP Analysis's `ip_geofencing_by_country`, except that `states` keys are ISO 3166-2 codes (`US-NJ`), not state names, because the position is resolved to a subdivision rather than to a provider's city label. A country that is not listed is allowed. Saving a region rule for a country with no published ISO 3166-2 boundaries is rejected rather than silently ignored. |
323
377
  | `geolocation_integrity_missing_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a native client submitted a position with no device-attestation token. Defaults to No action; web clients are recorded as unsupported rather than missing, because no browser can attest. |
324
378
  | `geolocation_ip_distance_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the device position and the session's IP location are further apart than `geolocation_ip_distance_km`, after both uncertainty radii are subtracted. |
325
- | `geolocation_ip_distance_km` | integer \| null | integer >=0 | |
379
+ | `geolocation_ip_distance_km` | integer \| null | integer >=0 | How far apart, in kilometres, the device position and the IP location may be, after both uncertainty radii are subtracted, before `geolocation_ip_distance_action` applies. 200 when the key is omitted; null switches the comparison off. Only a node whose `geolocation_position_source` is `device_and_ip` or unset compares; that key says which IP location it compares with. |
326
380
  | `geolocation_ip_distance_unit` | string \| null | 'imperial'\|'metric' | The unit the console shows `geolocation_ip_distance_km` in. Display only: the stored value is always kilometres and no rule depends on it. |
327
381
  | `geolocation_low_accuracy_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no attempt established the required precision: the best position has an uncertainty radius wider than `geolocation_max_accuracy_radius_m`, or it reported no radius at all. A position without a radius is never counted as meeting the limit. |
328
- | `geolocation_max_accuracy_radius_m` | integer \| null | integer | |
382
+ | `geolocation_low_accuracy_behavior` | string \| null | 'ask_again'\|'fail' | What a position wider than `geolocation_max_accuracy_radius_m`, or with no radius, does: `ask_again` (the default) asks the person to try again while attempts remain; `fail` ends the step on the first one. |
383
+ | `geolocation_max_accuracy_radius_m` | integer \| null | integer | The widest uncertainty radius, in metres, a device position may have and still count. From 10 to 50000 metres; 250 when unset. A wider position, or one that reports no radius, does what `geolocation_low_accuracy_behavior` says and is judged by `geolocation_low_accuracy_action`. An `ip_only` node has no device radius and never applies it. |
329
384
  | `geolocation_max_accuracy_radius_unit` | string \| null | 'imperial'\|'metric' | The unit the console shows `geolocation_max_accuracy_radius_m` in. Display only: the stored value is always metres, no rule depends on it, and the step data only forwards it so a client can show the same unit. |
330
- | `geolocation_max_age_seconds` | integer \| null | integer | |
331
- | `geolocation_max_attempts` | integer \| null | integer | |
385
+ | `geolocation_max_age_seconds` | integer \| null | integer | How old, in seconds, a device position may be when the server receives it. From 5 to 3600 seconds; 120 when unset. An older one is asked again while attempts remain and then judged by `geolocation_stale_fix_action`. |
386
+ | `geolocation_max_attempts` | integer \| null | integer | How many attempts the person gets on this node. From 1 to 5 attempts; 3 when unset. An attempt the person can still change (a refusal, a wide, stale or approximate position, or an area or anonymizer finding the node acts on) asks again while attempts remain, and the last one decides the step. A mocked position, or an emulator the node acts on, ends the step on the attempt that reported it. |
332
387
  | `geolocation_mock_location_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the operating system reported the position as simulated rather than measured (Android mock provider, iOS simulated-by-software). |
333
388
  | `geolocation_permission_denied_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the user declined or dismissed the location prompt on every allowed attempt. Defaults to Review: a refusal is a choice, not a fraud signal. |
389
+ | `geolocation_position_source` | string \| null | 'device_and_ip'\|'device_only'\|'ip_only' | Where the position comes from. `device_and_ip` asks for the device position and compares it with the IP location of the connection it is submitted from (an IP-intelligence lookup when that IP is not cached yet). Unset (the default) asks for the device position too and, as before this key existed, compares it with the IP location the session's Device & IP Analysis step observed, so there is no distance without that step and the connection is never looked up. The exception is a node that acts on a VPN, proxy or Tor finding (its own action or its preset): it looks the connection up for that finding and compares the device with it, exactly as `device_and_ip` does. `device_only` never compares with the IP location and looks the connection up only for those findings; `ip_only` never asks the person and judges the connection's IP location instead, city level with a 50 km radius, with no accuracy, freshness or approximate-grant rule; with `geolocation_areas` a coastal city is judged inside its country unless another country is within that radius. On a node that asks the device, an attempt with no device position is judged as the refusal or failure it is: the IP location never stands in for it. |
390
+ | `geolocation_preset` | string \| null | 'fraud_screening'\|'licensing' | The defaults every unset action of this node takes. `licensing`: outside an area, in a blocked area, a VPN, Tor or an emulator declines, a proxy and the other findings are reviewed, and a missing device attestation stays No action. `fraud_screening`: the same, except that what Licensing declines goes to review. Null keeps the long-standing defaults. An action set explicitly always wins. |
391
+ | `geolocation_proxy_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the connection that shared the location goes through an open, anonymous or private-relay proxy. No action unless set or a preset says otherwise. |
392
+ | `geolocation_refusal_path` | string \| null | 'continue_without_location'\|'end_session'\|'retry_then_handoff' | The way forward offered when location access is refused. `retry_then_handoff` (the default) asks again while attempts remain and offers a phone hand-off; `continue_without_location` lets the person go on, recording the refusal; `end_session` ends the step and the session on the first refusal, and needs `geolocation_permission_denied_action` to be Review or Decline and a workflow with a Declined, In Review or Final decision ending. The session is decided from the steps that ran and never Approved: on a workflow that cannot end on that decision it takes the other non-approving ending (Declined for In Review, In Review for Declined). |
334
393
  | `geolocation_stale_fix_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the position was measured more than `geolocation_max_age_seconds` before the server received it. |
335
- | `geolocation_timeout_seconds` | integer \| null | integer | |
394
+ | `geolocation_timeout_seconds` | integer \| null | integer | How long, in seconds, the client lets the device look for a position on each attempt; the server forwards it in the step data and enforces nothing itself. From 5 to 120 seconds; 20 when unset. An attempt that finds no position in time is submitted as `timeout`, asked again while attempts remain and then judged by `geolocation_unavailable_action`. |
395
+ | `geolocation_tor_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the connection that shared the location is a Tor exit node. No action unless set or a preset says otherwise. |
396
+ | `geolocation_travel_max_days` | integer \| null | integer | How long after being seen in the usual area a distant position is still travel. From 1 to 90 days; 14 when unset. |
397
+ | `geolocation_travel_tolerance_enabled` | boolean \| null | boolean | Excuse the distance from the address when the same person (same `vendor_data`) was seen within `geolocation_travel_usual_area_km` of it in the last `geolocation_travel_max_days` days. Never excuses a VPN, a spoofed position, a blocked area or being outside the allowed areas. Only a position the device measured counts as being seen there: a mocked or simulated fix, an emulator or a failed attestation never does. |
398
+ | `geolocation_travel_usual_area_km` | integer \| null | integer | Radius around the address that counts as the person's usual area. From 10 to 500 km; 100 when unset. |
336
399
  | `geolocation_unavailable_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no position could be obtained - location services off or restricted, the positioning system returned nothing, the attempt timed out, the user skipped the step, or the client is too old to support it. |
337
- | `is_geolocation_geofencing_enabled` | boolean \| null | boolean | |
400
+ | `geolocation_vpn_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the connection that shared the location is a commercial VPN. Unless it is No action, the person is asked to turn it off and check again while attempts remain. No action unless set or a preset says otherwise. |
401
+ | `is_geolocation_geofencing_enabled` | boolean \| null | boolean | Turns the area rules on: `geolocation_areas`, or the older `geolocation_geofencing_by_country`, only apply while this is true, and only then does the step data list `available_areas`. Off by default. With it on, a `geolocation_areas` list needs at least one allowed area. |
338
402
  | `status_rules` | array | array | |
339
403
 
340
404
  ### IP_ANALYSIS
@@ -352,6 +416,8 @@ Configuration for Device & IP Analysis feature.
352
416
  | `device_emulator_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the device is an emulator rather than real hardware. |
353
417
  | `device_hooking_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when runtime hooking or instrumentation is detected. |
354
418
  | `device_integrity_missing_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no platform device-integrity attestation was returned. |
419
+ | `device_liveness_attack_history_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the same device (matched on its persistent device id) was used in an earlier session of another user whose liveness capture the liveness engine judged an attack (risk DEVICE_LINKED_TO_LIVENESS_ATTACK). Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
420
+ | `device_model_inconsistency_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the same device (matched on its persistent device id) was reported as a different device model in an earlier session (risk DEVICE_MODEL_INCONSISTENT), which points at a spoofed device model or a copied device identifier. Generic model strings (for example `iPhone` or the reduced user agent `K`) are never compared. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
355
421
  | `device_rooted_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the device is rooted or jailbroken. |
356
422
  | `duplicated_device_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when this device was already used by another verified user. |
357
423
  | `duplicated_ip_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when this IP was already used by another verified user. |
@@ -377,6 +443,7 @@ Configuration for Device & IP Analysis feature.
377
443
  | `kyb_document_non_critical_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a document contradicts the registry on a minor detail. |
378
444
  | `kyb_document_subtype_config` | json \| null | {"<KYB_DOCUMENT_GROUP\|KYB_DOCUMENT_SUBTYPE>": {"enabled": true\|false, "max_age_days": <0-3650>\|-1\|null}} | Per-group or per-subtype switch and freshness window. Keys must be a known KYB document group or subtype code. `max_age_days` is null for the default window, -1 for unlimited, or an integer 0-3650; anything else is rejected. |
379
445
  | `kyb_document_tampering_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a company document looks tampered with. |
446
+ | `kyb_document_unproven_text_replacement_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a text field of a company document was blanked and re-typed in another font and the file holds no proof of whether its content changed (`KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`). Other editing evidence on the same document stays under `kyb_document_tampering_action`; when both apply, the stricter action decides. |
380
447
  | `kyb_required_document_groups` | json \| null | ["<KYB_DOCUMENT_GROUP>", ...] | The company paperwork to collect, as a list of document-GROUP codes - each group is satisfied by any one of the document types it covers. The KYB Documents feature refuses to save with an empty list: a node that requires nothing is the same as not having the node. |
381
448
  | `status_rules` | array | array | |
382
449
 
@@ -430,6 +497,7 @@ Configuration for Liveness feature.
430
497
  | `cross_org_identity_claim_pattern_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when other organizations in the network recorded identity-claim events for this same person in which the claimed identity did not match. Review or no action only - a decline set here is downgraded to review. |
431
498
  | `external_capture_device_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an external capture device is detected. |
432
499
  | `face_audio_recording_enabled` | boolean \| null | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default. |
500
+ | `face_liveness_attack_face_match_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the liveness face matches (above the duplicate-face similarity bar) a face from an earlier session of this application whose own capture the liveness engine judged an attack (risk FACE_MATCHES_LIVENESS_ATTACK), another user's session only and only a confident attack verdict. Review or no action only - a decline set here is downgraded to review, because a genuine user can be rejected once by mistake and then pass. Defaults to NO_ACTION (evidence is recorded, the verdict is unchanged). |
433
501
  | `face_liveness_duplicated_face_document_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a duplicate face is found on a user verified with a different date of birth. Another document of the same person (a passport after an identity card, a renewal, a document of a second country) is not flagged. |
434
502
  | `face_liveness_duplicated_face_name_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a duplicate face is found under a different name. |
435
503
  | `face_liveness_flash_mode` | string \| null | string | |
@@ -463,6 +531,12 @@ Configuration for NFC/ePassport feature.
463
531
  | Key | Type | Accepts | Meaning |
464
532
  | --- | --- | --- | --- |
465
533
  | `allow_nfc_skip` | boolean \| null | boolean | |
534
+ | `jpki_certificate_invalid_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a My Number Card certificate does not chain to the JPKI certification authority, is outside its validity period or is not a card certificate of the requested type. Default DECLINE. |
535
+ | `jpki_certificate_revoked_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the revocation check reports a My Number Card certificate revoked. Default DECLINE. |
536
+ | `jpki_inconsistent_data_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the name, date of birth, sex or address in the My Number Card's signature certificate differs from the OCR data of the same card. Default REVIEW. |
537
+ | `jpki_request_attributes` | boolean \| null | boolean | Japan My Number Card (JPKI, native SDKs only): also read the signature certificate, which needs the card's signature PIN and carries the holder's name, date of birth, sex and address, compared with the OCR data. Default true; false reads only the user authentication certificate (4-digit PIN), which proves the card and PIN but carries no attributes. |
538
+ | `jpki_revocation_unchecked_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the My Number Card was verified but its revocation status could not be checked. Default REVIEW. |
539
+ | `jpki_signature_invalid_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the My Number Card's signature over the one-time challenge does not verify, so possession of the card and knowledge of its PIN are not proven. Default DECLINE. |
466
540
  | `skip_nfc_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the user skips the NFC chip read (only reachable with `allow_nfc_skip`). |
467
541
  | `status_rules` | array | array | |
468
542
  | `trust_anchor_missing_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when chip data-group hashes are intact but the certificate chain cannot be verified because the issuing country's CSCA trust anchor is not loaded. |
@@ -475,6 +549,8 @@ Configuration for OCR/ID Verification feature.
475
549
 
476
550
  | Key | Type | Accepts | Meaning |
477
551
  | --- | --- | --- | --- |
552
+ | `address_not_verified_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when Address Validation could not confirm the address to the building (ADDRESS_NOT_VERIFIED: `partially_verified` or `not_verified`). Applies only while `address_validation_enabled` is on; an `unavailable` validation never raises it. Defaults to NO_ACTION, which only records the warning. |
553
+ | `address_validation_enabled` | boolean \| null | boolean | Validate the address this node reads (the one printed on the identity document, or the one on the proof of address) against postal reference data: it confirms the address exists and normalises it, and never links it to a person. The result is the `address_validation` object of the node's decision entry. A paid add-on, charged per address validated (a validation that could not run is free); off by default. |
478
554
  | `age_restrictions_by_country` | json \| null | {"<ISO3>": {"minimum_age": 1-120, "maximum_age": 1-120\|null, "states"?: {"<STATE_CODE>": {"minimum_age": 1-120, "maximum_age": 1-120\|null}}}} | Per-country (and optionally per-state) age gate. `minimum_age` is required for every country listed; `maximum_age` may be null. |
479
555
  | `critical_field_occlusion_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a critical printed field - an identity number, a name, the date of birth or the expiry date - was physically covered on the captured document. Defaults to REVIEW. |
480
556
  | `cross_org_fraud_document_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when this document was flagged as fraudulent by another organization in the network. |
@@ -499,6 +575,7 @@ Configuration for OCR/ID Verification feature.
499
575
  | `expected_details_mismatch_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the extracted identity contradicts the `expected_details` sent with the session. |
500
576
  | `expiration_date_not_detected_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no expiry date could be read from the document. |
501
577
  | `id_document_quality_threshold` | integer \| null | integer >=0 <=100 | |
578
+ | `id_verification_injection_attack_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the document (or the ID-lookup selfie) was injected rather than captured by the device's own camera (INJECTION_ATTACK_DETECTED): a software virtual camera, a camera feed generated by the page or by browser automation, a hooked camera, or an instrumentation tool attached to the app. Defaults to DECLINE: each of these proves the frames did not come from the device's own camera. Heuristic capture signals (FRAME_INJECTION_SUSPECTED and the others) are not covered and stay information. |
502
579
  | `id_verification_max_retry_attempts` | integer \| null | integer >=2 <=5 | |
503
580
  | `id_verification_name_match_score_threshold` | integer \| null | integer >=0 <=100 | |
504
581
  | `image_capture_methods_allowed` | array \| null | ["CAMERA_SCAN" \| "UPLOAD", ...] | Capture methods the end user may use for the document photo. Declared as a list of free strings, so the vocabulary is not in the field itself: CAMERA_SCAN (live capture) and UPLOAD (pick an existing file). An empty list falls back to the account default. |
@@ -516,7 +593,7 @@ Configuration for OCR/ID Verification feature.
516
593
  | `is_ocr_id_verification_data_review_enabled` | boolean \| null | boolean | Let the user review and correct the extracted identity data before the step completes. Off by default. A correction is scored against `ocr_id_verification_data_review_critical_fields`, and a disagreement takes the critical or the minor action accordingly. The review still runs when the workflow includes NFC - a later chip read simply supersedes it. |
517
594
  | `maximum_age` | integer \| null | integer >=1 <=120 | |
518
595
  | `maximum_age_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder is older than `maximum_age`. |
519
- | `methods` | json \| null | {"<ISO3>": {"document": {"enabled": bool}, "id_lookup": {"enabled": bool, "source"?: "<source_id>"\|null, "max_attempts": 1-5, "skip_liveness_and_face_match": bool, "on_partial_match": "fallback_to_document"\|"decline", "on_no_match": "fallback_to_document"\|"decline", "on_provider_error": "fallback_to_document"\|"decline", "response_fields"?: ["<field_key>", ...]}, "wallet": {"enabled": bool, "providers": ["<wallet_id>", ...], "on_failure": "fallback_to_document"\|"decline"}}} | Which ID verification methods each country may use: document capture (today's behaviour), non-doc lookup against a government or other authoritative source, and digital identity wallets. Omit the key, or a country, or a method, and that country is document only. Every method must be available for the country in the capability catalog (GET workflow-graph/id-verification-methods-catalog/); wallets are an accept-list with no ordering. Each fallback is `fallback_to_document` or `decline`; `max_attempts` (1-5, default 1) counts only lookups the registry answered. Where the catalog lists several lookup `sources` for a country, `source` picks exactly one by id; omitted means the country's default (the first listed). |
596
+ | `methods` | json \| null | {"<ISO3>": {"document": {"enabled": bool, "fallback_only"?: bool}, "id_lookup": {"enabled": bool, "source"?: "<source_id>"\|null, "max_attempts": 1-5, "skip_liveness_and_face_match": bool, "on_partial_match": "fallback_to_document"\|"decline", "on_no_match": "fallback_to_document"\|"decline", "on_provider_error": "fallback_to_document"\|"decline", "response_fields"?: ["<field_key>", ...]}, "wallet": {"enabled": bool, "providers": ["<wallet_id>", ...], "on_failure": "fallback_to_document"\|"decline"\|"retry"}}} | Which ID verification methods each country may use: document capture (today's behaviour), non-doc lookup against a government or other authoritative source, and digital identity wallets. Omit the key, or a country, or a method, and that country is document only. Every method must be available for the country in the capability catalog (GET workflow-graph/id-verification-methods-catalog/); wallets are an accept-list with no ordering. Each lookup fallback is `fallback_to_document` or `decline`; `wallet.on_failure` also accepts `retry` (see below); `max_attempts` (1-5, default 1) counts only lookups the registry answered. Where the catalog lists several lookup `sources` for a country, `source` picks exactly one by id; omitted means the country's default (the first listed). `document.fallback_only: true` keeps document capture out of the first screen: users start with the wallet or lookup and only those it fails reach document capture. It needs document capture enabled and a wallet or lookup in the country that falls back to it. `wallet.on_failure: retry` keeps a user whose sign-in failed on the wallet step to try again: the session is never declined for it and no document is offered. |
520
597
  | `minimum_age` | integer \| null | integer >=1 <=120 | |
521
598
  | `minimum_age_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the holder is younger than `minimum_age`. |
522
599
  | `ocr_id_verification_data_review_critical_fields` | array \| null | ["first_name" \| "last_name" \| "date_of_birth" \| ...] | Which extracted identity fields count as critical when the user edits the OCR result, so a mismatch takes the critical action rather than the minor one. |
@@ -560,8 +637,11 @@ Configuration for Proof of Address feature.
560
637
 
561
638
  | Key | Type | Accepts | Meaning |
562
639
  | --- | --- | --- | --- |
640
+ | `address_not_verified_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when Address Validation could not confirm the address to the building (ADDRESS_NOT_VERIFIED: `partially_verified` or `not_verified`). Applies only while `address_validation_enabled` is on; an `unavailable` validation never raises it. Defaults to NO_ACTION, which only records the warning. |
641
+ | `address_validation_enabled` | boolean \| null | boolean | Validate the address this node reads (the one printed on the identity document, or the one on the proof of address) against postal reference data: it confirms the address exists and normalises it, and never links it to a person. The result is the `address_validation` object of the node's decision entry. A paid add-on, charged per address validated (a validation that could not run is free); off by default. |
563
642
  | `poa_document_authenticity_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the document fails authenticity checks. |
564
643
  | `poa_document_issues_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the document is damaged, cropped or otherwise unusable. |
644
+ | `poa_document_unproven_text_replacement_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when a text field was blanked and re-typed in another font and the file holds no proof of whether its content changed (`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`). Other editing evidence on the same document stays under `poa_document_authenticity_action`; when both apply, the stricter action decides. |
565
645
  | `poa_documents_allowed` | json \| null | {"<ISO3>": {"<DOC_CODE>": {"enabled": 0\|1, "sides"?: 1\|2, "subtypes"?: ["<SUBTYPE_CODE>", ...]}}} | Which proof-of-address documents are accepted, per issuing country. Same shape as OCR's `documents_allowed`; omit to accept the full catalog. |
566
646
  | `poa_issue_date_not_detected_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when no issue date could be read from the document. |
567
647
  | `poa_issuer_not_identified_action` | string \| null | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the issuing company or authority cannot be identified. |
@@ -585,6 +665,28 @@ Configuration for Questionnaire feature.
585
665
  | `review_questionnaire_manually` | boolean \| null | boolean | |
586
666
  | `status_rules` | array | array | |
587
667
 
668
+ ### SIGNATURE
669
+
670
+ | Key | Type | Accepts | Meaning |
671
+ | --- | --- | --- | --- |
672
+ | `signature_consent_per_document` | boolean | boolean | |
673
+ | `signature_declined_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the signer declines; nothing is charged. |
674
+ | `signature_document_changed_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when an original no longer matches its captured SHA-256. |
675
+ | `signature_documents` | json | [{"uuid":"UUID", "title":"string", "file_name":"string", "pages":1, "size_bytes":1}] | Ordered documents previously uploaded to this workflow (a Word file is stored as its converted PDF); metadata is read from stored files. Fields placed on a document are managed on its signature-documents/{document}/fields/ route, not in this list. |
676
+ | `signature_documents_source` | string | 'both'\|'session'\|'workflow' | |
677
+ | `signature_email_signed_copy` | boolean | boolean | |
678
+ | `signature_evidence_page` | boolean | boolean | |
679
+ | `signature_format` | string | 'cades'\|'pades'\|'xades' | |
680
+ | `signature_identity_not_verified_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the signer lacks approved identity evidence. |
681
+ | `signature_level` | string | 'aes'\|'qes'\|'simple' | `simple` (default) needs no ID verification, email or phone: the signer types their name (or uses a verified one the session already has) and signs on the session link, with no code. `aes` needs an approved ID verification and a verified email or phone, and confirms with a one-time code. `qes` is not available yet and is refused. `simple` is only valid for `signature_signer: verified_person`. Simple suits low-risk agreements; regulated or high-value contracts should use `aes`. |
682
+ | `signature_link_validity_days` | integer | integer >=1 <=30 | |
683
+ | `signature_name_mismatch_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict when the verified name does not match the requested signer. |
684
+ | `signature_otp_channel` | string | 'email'\|'sms' | |
685
+ | `signature_otp_failed_action` | string | 'NO_ACTION'\|'REVIEW'\|'DECLINE' | Verdict after three invalid one-time codes. |
686
+ | `signature_require_read_to_end` | boolean | boolean | |
687
+ | `signature_signer` | string | 'key_people'\|'legal_representative'\|'verified_person' | |
688
+ | `status_rules` | array | array | |
689
+
588
690
  <!-- END GENERATED FEATURE CONFIG REFERENCE -->
589
691
 
590
692
  ## Contributing
@@ -0,0 +1,5 @@
1
+ /** Request headers for a public product API that authenticates with the application API key. */
2
+ export declare function applicationApiKeyHeaders(): Promise<Record<string, string>>;
3
+ /** The resolved application's API key, read fresh on every call. */
4
+ export declare function applicationApiKey(): Promise<string>;
5
+ //# sourceMappingURL=app-api-key.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app-api-key.d.ts","sourceRoot":"","sources":["../src/app-api-key.ts"],"names":[],"mappings":"AA2CA,gGAAgG;AAChG,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEhF;AAED,oEAAoE;AACpE,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAuCzD"}
@@ -0,0 +1,108 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.applicationApiKeyHeaders = applicationApiKeyHeaders;
4
+ exports.applicationApiKey = applicationApiKey;
5
+ const config_1 = require("./config");
6
+ const security_1 = require("./security");
7
+ // The application API key behind the standalone phone OTP endpoints.
8
+ //
9
+ // `POST /phone/send/` and `POST /phone/check/` are public product APIs, not console
10
+ // endpoints. Their only permission class is `IsValidClient` (service-didit-verification
11
+ // `core/permissions.py:183`), which accepts an introspected credential carrying NO
12
+ // `identifier`: an application `x-api-key`. A user Bearer always carries one
13
+ // (service-didit-auth `authorizations/processors/tokens.py:265`), so it is refused there.
14
+ //
15
+ // The other standalone tools reach their APIs through the console's user-Bearer proxy
16
+ // (`/organization/{org}/application/{app}/apis/<check>/`, gated on `create:sessions`),
17
+ // but that proxy registers only aml, id-verification, poa, kyb/*, phone-risk,
18
+ // email-risk, ip-risk and fraud-check (`applications/urls.py:1486-1573`): there is no
19
+ // `…/apis/phone/send/` or `…/apis/phone/check/`, and both answer 404 on staging and
20
+ // production. The application API key is therefore the only credential that works.
21
+ //
22
+ // The MCP reads it the two supported ways the auth service hands it to a user:
23
+ // 1. The console's application read, `GET /organizations/{org}/applications/{app}`
24
+ // (`organizations/views/application.py:86`): `read:applications` to read it at all,
25
+ // and `client_secret` is blanked unless the role holds `create:sessions`
26
+ // (`organizations/serializers/applications.py:100`), the same permission every other
27
+ // standalone tool needs. It only takes console-client tokens, which MCP sign-ins are.
28
+ // 2. When that read is refused outright (a local `didit_account_login` token is minted for
29
+ // the user's own application, not the console), the membership read
30
+ // `GET /organizations/me/{org}/applications/{app}/` returns it as `api_key`
31
+ // (`organizations/views/me.py:68`) to organization owners and admins only (`me.py:286`).
32
+ // That read checks the grant's organizations but not its scopes, so a sign-in refused
33
+ // for its scopes never falls back to it: the key stays behind the user's consent.
34
+ // Both blank a live application's key for a console browser session while staging's
35
+ // LIVE_PRIMARY_SECRET_REVEAL_ONLY is on (`organizations/services/secret_step_up.py:204`);
36
+ // MCP tokens are not console sessions and keep it.
37
+ //
38
+ // The key is a live secret. It is never cached in module state, never returned to a
39
+ // caller, never logged (audit-log.ts records argument keys and a digest only) and never
40
+ // interpolated into an error message.
41
+ // The auth service's refusal when an MCP sign-in's consented scopes do not cover the request
42
+ // (service-didit-auth `core/permissions.py:312`). The application read needs the
43
+ // `applications` resource, which only didit:management grants (`authorizations/config/mcp_scopes.py:50`).
44
+ const MCP_SCOPE_REFUSAL = /token's scope does not permit this action/;
45
+ /** Request headers for a public product API that authenticates with the application API key. */
46
+ async function applicationApiKeyHeaders() {
47
+ return { "Content-Type": "application/json", "x-api-key": await applicationApiKey() };
48
+ }
49
+ /** The resolved application's API key, read fresh on every call. */
50
+ async function applicationApiKey() {
51
+ const org = (0, security_1.pathSegment)((0, config_1.resolveOrganizationId)(), "organization_id");
52
+ const app = (0, security_1.pathSegment)((0, config_1.resolveApplicationId)(), "application_id");
53
+ let key;
54
+ try {
55
+ // The console detail route is declared WITHOUT a trailing slash (APPEND_SLASH only adds one).
56
+ const application = await (0, config_1.apiRequest)(`/organizations/${org}/applications/${app}`, {
57
+ baseUrl: config_1.DIDIT_AUTH_BASE_URL,
58
+ });
59
+ key = application?.client_secret;
60
+ }
61
+ catch (error) {
62
+ if (!isForbidden(error))
63
+ throw error;
64
+ if (MCP_SCOPE_REFUSAL.test(error.shape.message)) {
65
+ throw new security_1.DiditError({
66
+ ...error.shape,
67
+ code: "missing_scope",
68
+ hint: "These tools send the code with the application's API key, and reading it needs the " +
69
+ "didit:management scope, which this sign-in was not granted. Sign in to the Didit MCP " +
70
+ "connector again with didit:management as well as didit:verification.",
71
+ });
72
+ }
73
+ key = await ownerOrAdminApplicationKey(`/organizations/me/${org}/applications/${app}/`);
74
+ }
75
+ if (typeof key !== "string" || !key.trim()) {
76
+ throw new security_1.DiditError({
77
+ code: "missing_scope",
78
+ message: "Didit returned no API key for this application to your sign-in.",
79
+ hint: "These tools send the code with the application's API key, which Didit only shows to a role " +
80
+ "holding create:sessions (Owner, Admin and Developer have it). A console browser session cannot " +
81
+ "read a live application's key where the console hides it: sign in through the Didit MCP " +
82
+ "connector instead.",
83
+ });
84
+ }
85
+ return key;
86
+ }
87
+ async function ownerOrAdminApplicationKey(path) {
88
+ try {
89
+ const application = await (0, config_1.apiRequest)(path, { baseUrl: config_1.DIDIT_AUTH_BASE_URL });
90
+ return application?.api_key;
91
+ }
92
+ catch (error) {
93
+ // Say which roles can read the key instead of the generic "may require a different role".
94
+ if (isForbidden(error)) {
95
+ throw new security_1.DiditError({
96
+ ...error.shape,
97
+ hint: "These tools send the code with the application's API key, and this sign-in cannot read it. " +
98
+ "Through the Didit MCP connector it needs a role with create:sessions (Owner, Admin or " +
99
+ "Developer); with a local didit_account_login token, an organization owner or admin.",
100
+ });
101
+ }
102
+ throw error;
103
+ }
104
+ }
105
+ function isForbidden(error) {
106
+ return error instanceof security_1.DiditError && error.shape.status === 403;
107
+ }
108
+ //# sourceMappingURL=app-api-key.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app-api-key.js","sourceRoot":"","sources":["../src/app-api-key.ts"],"names":[],"mappings":";;AA4CA,4DAEC;AAGD,8CAuCC;AAxFD,qCAAwG;AACxG,yCAAqD;AAErD,qEAAqE;AACrE,EAAE;AACF,oFAAoF;AACpF,wFAAwF;AACxF,mFAAmF;AACnF,6EAA6E;AAC7E,0FAA0F;AAC1F,EAAE;AACF,sFAAsF;AACtF,uFAAuF;AACvF,8EAA8E;AAC9E,sFAAsF;AACtF,oFAAoF;AACpF,mFAAmF;AACnF,EAAE;AACF,+EAA+E;AAC/E,qFAAqF;AACrF,yFAAyF;AACzF,8EAA8E;AAC9E,0FAA0F;AAC1F,2FAA2F;AAC3F,6FAA6F;AAC7F,yEAAyE;AACzE,iFAAiF;AACjF,8FAA8F;AAC9F,2FAA2F;AAC3F,uFAAuF;AACvF,oFAAoF;AACpF,0FAA0F;AAC1F,mDAAmD;AACnD,EAAE;AACF,oFAAoF;AACpF,wFAAwF;AACxF,sCAAsC;AAEtC,6FAA6F;AAC7F,iFAAiF;AACjF,0GAA0G;AAC1G,MAAM,iBAAiB,GAAG,2CAA2C,CAAC;AAEtE,gGAAgG;AACzF,KAAK,UAAU,wBAAwB;IAC5C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,iBAAiB,EAAE,EAAE,CAAC;AACxF,CAAC;AAED,oEAAoE;AAC7D,KAAK,UAAU,iBAAiB;IACrC,MAAM,GAAG,GAAG,IAAA,sBAAW,EAAC,IAAA,8BAAqB,GAAE,EAAE,iBAAiB,CAAC,CAAC;IACpE,MAAM,GAAG,GAAG,IAAA,sBAAW,EAAC,IAAA,6BAAoB,GAAE,EAAE,gBAAgB,CAAC,CAAC;IAElE,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,8FAA8F;QAC9F,MAAM,WAAW,GAAG,MAAM,IAAA,mBAAU,EAAC,kBAAkB,GAAG,iBAAiB,GAAG,EAAE,EAAE;YAChF,OAAO,EAAE,4BAAmB;SAC7B,CAAC,CAAC;QACH,GAAG,GAAG,WAAW,EAAE,aAAa,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QACrC,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,qBAAU,CAAC;gBACnB,GAAG,KAAK,CAAC,KAAK;gBACd,IAAI,EAAE,eAAe;gBACrB,IAAI,EACF,qFAAqF;oBACrF,uFAAuF;oBACvF,sEAAsE;aACzE,CAAC,CAAC;QACL,CAAC;QACD,GAAG,GAAG,MAAM,0BAA0B,CAAC,qBAAqB,GAAG,iBAAiB,GAAG,GAAG,CAAC,CAAC;IAC1F,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,qBAAU,CAAC;YACnB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,iEAAiE;YAC1E,IAAI,EACF,6FAA6F;gBAC7F,iGAAiG;gBACjG,0FAA0F;gBAC1F,oBAAoB;SACvB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,KAAK,UAAU,0BAA0B,CAAC,IAAY;IACpD,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,IAAA,mBAAU,EAAC,IAAI,EAAE,EAAE,OAAO,EAAE,4BAAmB,EAAE,CAAC,CAAC;QAE7E,OAAO,WAAW,EAAE,OAAO,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0FAA0F;QAC1F,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,qBAAU,CAAC;gBACnB,GAAG,KAAK,CAAC,KAAK;gBACd,IAAI,EACF,6FAA6F;oBAC7F,wFAAwF;oBACxF,qFAAqF;aACxF,CAAC,CAAC;QACL,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,YAAY,qBAAU,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC;AACnE,CAAC"}