@didit-protocol/mcp-server 5.1.51 → 5.1.53

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 (117) hide show
  1. package/README.md +156 -14
  2. package/dist/account-session.d.ts +46 -0
  3. package/dist/account-session.d.ts.map +1 -0
  4. package/dist/account-session.js +262 -0
  5. package/dist/account-session.js.map +1 -0
  6. package/dist/api-key-connection.d.ts +77 -0
  7. package/dist/api-key-connection.d.ts.map +1 -0
  8. package/dist/api-key-connection.js +170 -0
  9. package/dist/api-key-connection.js.map +1 -0
  10. package/dist/app-api-key.d.ts.map +1 -1
  11. package/dist/app-api-key.js +4 -0
  12. package/dist/app-api-key.js.map +1 -1
  13. package/dist/audit-log.d.ts +2 -0
  14. package/dist/audit-log.d.ts.map +1 -1
  15. package/dist/audit-log.js +13 -0
  16. package/dist/audit-log.js.map +1 -1
  17. package/dist/auth/introspection-verifier.d.ts.map +1 -1
  18. package/dist/auth/introspection-verifier.js +10 -0
  19. package/dist/auth/introspection-verifier.js.map +1 -1
  20. package/dist/compress.d.ts +8 -0
  21. package/dist/compress.d.ts.map +1 -0
  22. package/dist/compress.js +90 -0
  23. package/dist/compress.js.map +1 -0
  24. package/dist/config.d.ts +12 -5
  25. package/dist/config.d.ts.map +1 -1
  26. package/dist/config.js +33 -6
  27. package/dist/config.js.map +1 -1
  28. package/dist/device-login.d.ts +5 -0
  29. package/dist/device-login.d.ts.map +1 -1
  30. package/dist/device-login.js +2 -0
  31. package/dist/device-login.js.map +1 -1
  32. package/dist/guidance.d.ts +53 -0
  33. package/dist/guidance.d.ts.map +1 -0
  34. package/dist/guidance.js +183 -0
  35. package/dist/guidance.js.map +1 -0
  36. package/dist/http.d.ts.map +1 -1
  37. package/dist/http.js +43 -5
  38. package/dist/http.js.map +1 -1
  39. package/dist/index.d.ts +33 -0
  40. package/dist/index.d.ts.map +1 -1
  41. package/dist/index.js +529 -121
  42. package/dist/index.js.map +1 -1
  43. package/dist/internal-tools.d.ts +6 -1
  44. package/dist/internal-tools.d.ts.map +1 -1
  45. package/dist/internal-tools.js +3 -2
  46. package/dist/internal-tools.js.map +1 -1
  47. package/dist/login-cli.d.ts.map +1 -1
  48. package/dist/login-cli.js +8 -0
  49. package/dist/login-cli.js.map +1 -1
  50. package/dist/mcp-modern.d.ts +9 -5
  51. package/dist/mcp-modern.d.ts.map +1 -1
  52. package/dist/mcp-modern.js +31 -8
  53. package/dist/mcp-modern.js.map +1 -1
  54. package/dist/orgapp.d.ts.map +1 -1
  55. package/dist/orgapp.js +14 -1
  56. package/dist/orgapp.js.map +1 -1
  57. package/dist/paging.d.ts +43 -0
  58. package/dist/paging.d.ts.map +1 -0
  59. package/dist/paging.js +98 -0
  60. package/dist/paging.js.map +1 -0
  61. package/dist/permissions.d.ts.map +1 -1
  62. package/dist/permissions.js +1 -0
  63. package/dist/permissions.js.map +1 -1
  64. package/dist/privileged-tools.d.ts +5 -1
  65. package/dist/privileged-tools.d.ts.map +1 -1
  66. package/dist/privileged-tools.js +2 -2
  67. package/dist/privileged-tools.js.map +1 -1
  68. package/dist/tools/auth.d.ts.map +1 -1
  69. package/dist/tools/auth.js +11 -4
  70. package/dist/tools/auth.js.map +1 -1
  71. package/dist/tools/billing.d.ts.map +1 -1
  72. package/dist/tools/billing.js +29 -0
  73. package/dist/tools/billing.js.map +1 -1
  74. package/dist/tools/blocklist.d.ts.map +1 -1
  75. package/dist/tools/blocklist.js +21 -0
  76. package/dist/tools/blocklist.js.map +1 -1
  77. package/dist/tools/cases.d.ts.map +1 -1
  78. package/dist/tools/cases.js +12 -0
  79. package/dist/tools/cases.js.map +1 -1
  80. package/dist/tools/context.d.ts.map +1 -1
  81. package/dist/tools/context.js +16 -0
  82. package/dist/tools/context.js.map +1 -1
  83. package/dist/tools/discovery.d.ts +50 -0
  84. package/dist/tools/discovery.d.ts.map +1 -0
  85. package/dist/tools/discovery.js +522 -0
  86. package/dist/tools/discovery.js.map +1 -0
  87. package/dist/tools/docs.d.ts +10 -0
  88. package/dist/tools/docs.d.ts.map +1 -0
  89. package/dist/tools/docs.js +137 -0
  90. package/dist/tools/docs.js.map +1 -0
  91. package/dist/tools/investigator.d.ts.map +1 -1
  92. package/dist/tools/investigator.js +4 -3
  93. package/dist/tools/investigator.js.map +1 -1
  94. package/dist/tools/questionnaires.d.ts +2 -1
  95. package/dist/tools/questionnaires.d.ts.map +1 -1
  96. package/dist/tools/questionnaires.js +3 -2
  97. package/dist/tools/questionnaires.js.map +1 -1
  98. package/dist/tools/search.d.ts +3 -1
  99. package/dist/tools/search.d.ts.map +1 -1
  100. package/dist/tools/search.js +20 -6
  101. package/dist/tools/search.js.map +1 -1
  102. package/dist/tools/sessions.d.ts +2 -1
  103. package/dist/tools/sessions.d.ts.map +1 -1
  104. package/dist/tools/sessions.js +3 -2
  105. package/dist/tools/sessions.js.map +1 -1
  106. package/dist/tools/settings.d.ts +4 -0
  107. package/dist/tools/settings.d.ts.map +1 -1
  108. package/dist/tools/settings.js +7 -0
  109. package/dist/tools/settings.js.map +1 -1
  110. package/dist/tools/transactions.d.ts.map +1 -1
  111. package/dist/tools/transactions.js +21 -0
  112. package/dist/tools/transactions.js.map +1 -1
  113. package/dist/toolsets.d.ts +87 -0
  114. package/dist/toolsets.d.ts.map +1 -0
  115. package/dist/toolsets.js +345 -0
  116. package/dist/toolsets.js.map +1 -0
  117. package/package.json +8 -3
package/README.md CHANGED
@@ -2,8 +2,13 @@
2
2
 
3
3
  The official [Model Context Protocol](https://modelcontextprotocol.io) server for [Didit](https://didit.me) — bring KYC, KYB, AML screening, transaction monitoring, biometrics, and full workspace operations to Claude, Cursor, VS Code, Windsurf, Zed, and any MCP client.
4
4
 
5
- - **140+ tools** across sessions, workflows, vendor users/businesses, transactions, networks, the standalone verification APIs, lists, cases, reports, webhooks, and billing.
6
- - **Auth is "Log in with Didit" (OAuth 2.1 + PKCE)** — the MCP acts as the signed-in **user** with their role's permissions. There is **no API-key mode**: every tool calls the user-scoped console endpoints, which only accept a Bearer token.
5
+ - **160+ tools** across sessions, workflows, vendor users/businesses, transactions, the standalone verification APIs, lists, cases, reports, webhooks, and billing.
6
+ - **Load only what you need.** Add `?toolsets=core` for a short catalog of about 30 tools, about a tenth of the tokens the full list costs; the rest stays one step away through `didit_tool_search`. See [Toolsets](#toolsets).
7
+ - **Read-only mode** for connections that must never change anything: add `?read_only=true`.
8
+ - **Two ways to connect.**
9
+ "Log in with Didit" (OAuth 2.1 + PKCE): the MCP acts as the signed-in **user** with their role's permissions.
10
+ Or an **application API key**, for agents that run with no person present (CI, scheduled jobs, backend agents): the connection is that one application.
11
+ See [Authentication](#authentication).
7
12
  - Tools call Didit REST endpoints. Session PDF generation returns a temporary download URL for the original PDF.
8
13
 
9
14
  > Full documentation: **https://docs.didit.me/integration/mcp/overview**
@@ -50,13 +55,15 @@ No install, no API key — point your client at the hosted URL and sign in via t
50
55
  https://mcp.didit.me/mcp
51
56
  ```
52
57
 
53
- **Claude Code**
54
-
55
- ```bash
56
- claude mcp add --transport http didit https://mcp.didit.me/mcp
57
- ```
58
+ | Client | Install |
59
+ |---|---|
60
+ | **Claude** (web, Desktop) | [Add Didit to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp) |
61
+ | **Claude Code** | `claude mcp add --transport http didit https://mcp.didit.me/mcp` |
62
+ | **Cursor** | [Add Didit to Cursor](https://cursor.com/install-mcp?name=didit&config=eyJ1cmwiOiJodHRwczovL21jcC5kaWRpdC5tZS9tY3AifQ%3D%3D) |
63
+ | **VS Code** (GitHub Copilot) | [Add Didit to VS Code](https://vscode.dev/redirect/mcp/install?name=didit&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.didit.me%2Fmcp%22%7D) |
64
+ | **OpenAI Codex** | `codex mcp add didit --url https://mcp.didit.me/mcp` |
58
65
 
59
- **Cursor** (`~/.cursor/mcp.json`)
66
+ **Cursor** (`~/.cursor/mcp.json`), by hand
60
67
 
61
68
  ```json
62
69
  { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
@@ -68,7 +75,9 @@ claude mcp add --transport http didit https://mcp.didit.me/mcp
68
75
  { "mcpServers": { "didit": { "command": "npx", "args": ["-y", "mcp-remote@latest", "https://mcp.didit.me/mcp"] } } }
69
76
  ```
70
77
 
71
- See [per-client setup](https://docs.didit.me/integration/mcp/installation) for Claude Desktop and VS Code.
78
+ See [per-client setup](https://docs.didit.me/integration/mcp/installation) for every client, with screenshots and troubleshooting.
79
+
80
+ Once connected, ask for "my Didit context" (the model calls `didit_context_get`), or start from one of the server's prompts: `integrate_didit`, `review_queue`, `explain_session`, `build_workflow`, `verification_report`.
72
81
 
73
82
  ### Sign in without a browser (device code)
74
83
 
@@ -100,21 +109,152 @@ Approve only a code you started yourself.
100
109
  - No shell? Ask the agent to call `didit_account_device_login_start`, show you the link and code, then `didit_account_device_login_poll` once you approve.
101
110
  Both tools exist only on the local server.
102
111
 
112
+ ### Sign in with the account tools
113
+
114
+ On the local server an agent can also sign in by itself, with an email address and a password: `didit_account_login` for an existing account (then `didit_account_verify_2fa` when the account has an authenticator app), or `didit_account_register` and `didit_account_verify_email` for a new one.
115
+ The local server keeps that sign-in, so the tools that follow are authenticated with nothing passed between them.
116
+
117
+ - It is kept in the same credentials file as a device-code sign-in (`~/.config/didit/mcp-credentials.json`, readable by you only) and refreshed before it expires.
118
+ A server started later picks it up.
119
+ - The answer of these tools carries no refresh token: the server holds it, because a refresh token works once.
120
+ - When the file cannot be written (a read-only home directory in a container), the sign-in is kept in memory until the server stops.
121
+ - If you signed in both ways, the server uses the more recent sign-in.
122
+ `DIDIT_ACCESS_TOKEN`, when set, still takes precedence over both.
123
+ - `npx -y @didit-protocol/mcp-server logout` removes it from the machine.
124
+ - An account that signs in with a passkey or SSO has no password: use the device code above.
125
+
126
+ These tools exist only on the local server.
127
+ The hosted server never takes a password.
128
+
129
+ ### Connect with an API key (headless agents and CI)
130
+
131
+ An agent that runs with no person present has no browser to sign in with.
132
+ It connects to the hosted server with the application API key it already sends to the Didit API, in the `x-api-key` header:
133
+
134
+ **Claude Code**
135
+
136
+ ```bash
137
+ claude mcp add --transport http didit https://mcp.didit.me/mcp --header "x-api-key: $DIDIT_API_KEY"
138
+ ```
139
+
140
+ **Cursor** (`~/.cursor/mcp.json`)
141
+
142
+ ```json
143
+ { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp", "headers": { "x-api-key": "${env:DIDIT_API_KEY}" } } } }
144
+ ```
145
+
146
+ **Any other client or your own agent:** send `x-api-key: <key>` on every request to `https://mcp.didit.me/mcp`.
147
+ `Authorization: Bearer <key>` works too, for clients that only let you set a bearer token.
148
+
149
+ What an API key connection is:
150
+
151
+ - **One application.**
152
+ The connection acts on the application the key belongs to, so there are no ids to pass.
153
+ `didit_context_get` names it, says whether it is `live` or `sandbox`, and reports `connection.type: "api_key"`.
154
+ A call that names another organization or application is refused.
155
+ - **The key's own access.**
156
+ The key is forwarded to the Didit API exactly as on a direct API call, and the API decides what it may do.
157
+ A full-access key reaches everything of its application; a restricted key only the resources it was given.
158
+ Give an agent a restricted key with an expiry, created in the Didit console under the application's API keys.
159
+ - **Sandbox first.**
160
+ Connect with the sandbox application's key to build and test: every check is simulated and nothing is billed.
161
+ - **Combines with toolsets and read-only:** `https://mcp.didit.me/mcp?toolsets=core&read_only=true` (see [Toolsets](#toolsets)).
162
+ - **Revoked like any key.**
163
+ Revoke or rotate the key in the console and the connection stops within a minute.
164
+ Every tool call is logged with the key's id, never the key.
165
+
166
+ What needs a person, and is therefore neither listed nor run on an API key connection:
167
+
168
+ - members, roles and API key management;
169
+ - the organization's plan, cards, receipts and billing details;
170
+ - the audit log, and `didit_workflow_build_graph` (use `didit_workflow_create`, or the graph tools `didit_workflow_create_draft`, `didit_workflow_validate_graph` and `didit_workflow_set_graph`);
171
+ - download links for session PDFs and e-signature files (request the file from the Didit API with the same key).
172
+
173
+ A person does those in the Didit console, or through a connection that signs in with OAuth.
174
+
175
+ Two limits to know:
176
+
177
+ - A key limited to specific IP addresses is refused, because the Didit API would see this server's address and not yours.
178
+ - `/mcp` and `/mcp/payments` take a key.
179
+ **From nothing to a first verification, with no browser.**
180
+ The account tools of the local server create the account: `didit_account_register`, then `didit_account_verify_email` with the code sent to the email address.
181
+ The answer carries the new organization with its live and its sandbox application, each with its API key.
182
+ The local server is signed in from that moment (see [Sign in with the account tools](#sign-in-with-the-account-tools)), so the same conversation goes on to create a workflow (`didit_workflow_create`) and a session (`didit_session_create`) in the sandbox application.
183
+ For an agent that runs elsewhere, store the keys in your secret store and connect it to the hosted server with the sandbox key; switch to the live key to go live.
184
+ `didit_org_get_balance` reads the credit balance; when credit is needed, see [Agent payments](#agent-payments-mcppayments-stdio).
185
+
186
+ `GET /healthz` lists `api_key` under `features` on a server that accepts keys.
187
+
103
188
  ## Authentication
104
189
 
105
190
  The MCP is an OAuth 2.1 **resource server**; the Didit console (`business.didit.me`) is the **authorization server**. On first connect your client opens a browser, you **Log in with Didit** and approve the scopes, and the MCP then acts as **you** — across every organization you belong to, with your role's permissions. Tokens are short-lived and refreshed automatically.
106
191
 
107
192
  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.
108
193
 
109
- > **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.)
110
- >
111
- > 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.
194
+ The hosted server also takes an **application API key** in place of a sign-in, for agents that run with no person present.
195
+ Such a connection is one application with the key's own access, not a user with a role: see [Connect with an API key](#connect-with-an-api-key-headless-agents-and-ci).
196
+
197
+ > The phone code pair, `didit_verify_phone_send` and `didit_verify_phone_check`, always calls the public phone API with the application's API key, because the console has no route for them.
198
+ > On a sign-in the MCP reads that 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); on an API key connection it uses the connection's own key.
199
+ > The key is never returned, stored or logged.
112
200
 
113
201
  See [Authentication](https://docs.didit.me/integration/mcp/authentication).
114
202
 
203
+ ## Toolsets
204
+
205
+ By default a connection lists every tool your role may use, as it always has.
206
+ Tool definitions are sent to the model with every request, so the whole catalog costs tens of thousands of tokens each time: roughly 50,000 to 115,000, depending on the model's tokenizer.
207
+ Some clients also cap how many tools they accept.
208
+ The short catalog trades that cost for one more step, a search for the tool: measured on a set of everyday requests, the strongest models reached the right tool a little more often with the full list, at about ten times the tokens.
209
+ When the cost matters (a coding agent with a context budget, a client that caps the number of tools), name the toolsets you want on the server URL:
210
+
211
+ ```
212
+ https://mcp.didit.me/mcp?toolsets=core
213
+ https://mcp.didit.me/mcp?toolsets=core,workflows
214
+ https://mcp.didit.me/mcp?toolsets=core,transactions,cases&read_only=true
215
+ ```
216
+
217
+ `core` is the short catalog: about 30 tools and about a tenth of the tokens.
218
+ It covers your organizations and applications, sessions (create, find, decide, explain, simulate in the sandbox, webhook deliveries), finding workflows, analytics and balance, the application's API key and webhooks, finding cases, users, businesses and transactions, and the documentation search.
219
+
220
+ | Toolset | What it holds |
221
+ |---|---|
222
+ | `core` | The short list above. |
223
+ | `account` | Organizations, applications, API keys, members and roles. |
224
+ | `billing` | Plan, credit balance, payment methods, receipts and billing details. |
225
+ | `sessions` | Verification sessions: create, find, decide, review, share, import, PDFs and webhook deliveries. |
226
+ | `workflows` | Verification workflows and questionnaires: build, edit, validate and publish. |
227
+ | `lists` | Custom lists, the blocklist and the allowlist. |
228
+ | `vendors` | The people and companies you verify: vendor users and vendor businesses. |
229
+ | `transactions` | Transaction monitoring: transactions, wallet screening and rules with backtesting. |
230
+ | `cases` | Case management: create, assign, escalate and resolve cases. |
231
+ | `investigator` | The AI Investigator: its review queue, reports, decisions, policy questions and performance. |
232
+ | `webhooks` | Webhook destinations and alerts. |
233
+ | `reports` | Analytics, exports and the audit log. |
234
+ | `branding` | White-label branding of the verification flow. |
235
+ | `verification` | Standalone verification APIs: ID document, face, AML, proof of address, phone, email, database and business checks. |
236
+ | `docs` | Search the Didit documentation. |
237
+ | `all` | Every tool your role may use. The default. |
238
+
239
+ How it behaves:
240
+
241
+ - **Toolsets are opt-in.** A URL with no `toolsets` lists everything, so an existing connection sees no difference.
242
+ - **Naming toolsets lists exactly those.** `?toolsets=cases` lists the case tools (and `didit_context_get`); add `core` to get the short list too.
243
+ - **A toolset decides what is listed, not what you may run.** A tool outside the selection still runs when called by name, with the same permission checks as always. Nothing is lost by loading less.
244
+ - **The rest stays one step away.** When a connection lists only part of the catalog it also gets four discovery tools: `didit_tool_search` (find a tool by what you want to do, or list a toolset), `didit_tool_describe` (its full schema), `didit_tool_call_read` and `didit_tool_call_write` (run it). A call through them is checked exactly like a direct call.
245
+ - **`read_only=true` is a safety boundary.** Only tools that read are listed or discoverable, and every call that would change data is refused, whatever the client lists or remembers. It works with or without `toolsets`.
246
+ - **An unknown toolset is ignored, never an error**, and the server's instructions name it back with the valid ids.
247
+ - **Clients that cannot edit the URL** send the `X-MCP-Toolsets` and `X-MCP-Readonly` headers instead.
248
+ - **The local (stdio) server** takes `--toolsets=core,workflows` and `--read-only`, or the `DIDIT_TOOLSETS` and `DIDIT_READ_ONLY` environment variables.
249
+ - **A self-hosted server** can change what a connection gets when it names nothing with `MCP_DEFAULT_TOOLSETS` (for example `core`).
250
+ - **`GET /healthz`** lists what the server supports (`"features": ["toolsets", "read_only", ...]`), for a client that wants to check before it relies on one.
251
+
252
+ The server also sends **instructions** on connect (where to start, how organization and application ids resolve, what this connection loaded) and offers **prompts** (`integrate_didit`, `review_queue`, `explain_session`, `build_workflow`, `verification_report`).
253
+ `didit_docs_search` searches the live documentation at docs.didit.me, so questions about how Didit works are answered from the current pages; set `DIDIT_DOCS_MCP_URL` to an empty string to switch it off.
254
+
115
255
  ## Tools
116
256
 
117
- 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:
257
+ 160+ tools, grouped by toolset. 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:
118
258
 
119
259
  - **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.
120
260
  - **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).
@@ -134,6 +274,7 @@ See [Authentication](https://docs.didit.me/integration/mcp/authentication).
134
274
  The directory-listed connectors (`/mcp` and `/mcp/chatgpt`) never move money: `didit_org_top_up` is not in their catalog and a call to it is refused with the console link.
135
275
  `https://mcp.didit.me/mcp/payments` is a separate, unlisted endpoint for coding agents that may top up the organization's saved card once a person turned that on.
136
276
  It uses the same OAuth sign-in and tokens as `/mcp` (its own protected-resource metadata is at `/.well-known/oauth-protected-resource/mcp/payments`), serves the full catalog plus `didit_org_top_up`, and is never submitted to a directory.
277
+ An [API key connection](#connect-with-an-api-key-headless-agents-and-ci) gets the same tool there, under the same switch.
137
278
  The local stdio server offers the same tool.
138
279
 
139
280
  `didit_org_top_up` parameters:
@@ -175,7 +316,8 @@ Both forms enforce the same 15MB cap and magic-bytes allow-list (png/jpg/jpeg/we
175
316
 
176
317
  ## Run it yourself
177
318
 
178
- The hosted server above is the easy path — no install. To self-host, clone this repo and run it with **Docker** or Node. It authenticates the user the same way (OAuth, or a user Bearer token for headless runs); there is no API-key mode.
319
+ The hosted server above is the easy path - no install. To self-host, clone this repo and run it with **Docker** or Node. It authenticates the same way: OAuth or an application API key on the hosted endpoint, or a user Bearer token (`DIDIT_ACCESS_TOKEN`) for a local headless run.
320
+ API keys need the default token verification mode (`MCP_TOKEN_VERIFY_MODE=introspection`).
179
321
 
180
322
  ```bash
181
323
  git clone https://github.com/didit-protocol/mcp.git && cd mcp
@@ -0,0 +1,46 @@
1
+ import { DeviceLoginDeps } from "./device-login";
2
+ /** Where the sign-in is kept: the credentials file, or this process's memory when the file cannot be written. */
3
+ export type KeptIn = {
4
+ where: "file";
5
+ path: string;
6
+ } | {
7
+ where: "memory";
8
+ };
9
+ /**
10
+ * Keep the sign-in an account tool just returned. `tokens` is the auth service's answer
11
+ * (`access_token`, `refresh_token`, `expires_in`); anything without an access token (a second
12
+ * factor step, an SSO notice) keeps nothing and returns undefined.
13
+ */
14
+ export declare function keepAccountSession(tokens: unknown, deps?: DeviceLoginDeps, authBaseUrl?: string, file?: string): KeptIn | undefined;
15
+ /** Remove the kept account-tools sign-in from this machine. Returns whether there was one. */
16
+ export declare function forgetAccountSession(authBaseUrl?: string, file?: string): boolean;
17
+ /**
18
+ * The kept account-tools access token, refreshed when it expires within 60 s. Concurrent callers
19
+ * share one refresh (a refresh token works once). Returns undefined when nothing is kept; throws
20
+ * login_required when the session is over.
21
+ */
22
+ export declare function accountSessionToken(deps?: DeviceLoginDeps, authBaseUrl?: string, file?: string): Promise<string | undefined>;
23
+ /**
24
+ * The access token of the local server's sign-in: the device-code one or the account-tools one,
25
+ * whichever the person did last. Returns undefined when neither exists.
26
+ */
27
+ export declare function localSignInToken(deps?: DeviceLoginDeps, consoleOrigin?: string, authBaseUrl?: string, file?: string): Promise<string | undefined>;
28
+ /**
29
+ * What an account tool answers once the server kept its sign-in: the same answer without the
30
+ * refresh token, and a line saying the next tools are authenticated. Answers that carry no
31
+ * access token (a second factor step, an SSO notice) pass through unchanged.
32
+ */
33
+ export declare function signedInAnswer(answer: unknown, kept: KeptIn | undefined): unknown;
34
+ /**
35
+ * What the server does with an account tool's answer: on the local server, keep the sign-in so
36
+ * the next tool is authenticated and take the refresh token out of what the model sees.
37
+ *
38
+ * A hosted server keeps nothing, ever: its process and its credentials file are shared by every
39
+ * caller, so one caller's refresh token must never land there. A hosted server already refuses
40
+ * the account tools before they run (index.ts); this is the same rule stated where the token is
41
+ * stored, so it holds whatever happens to that refusal.
42
+ */
43
+ export declare function keepSignIn(answer: unknown, options: {
44
+ hosted: boolean;
45
+ }, deps?: DeviceLoginDeps, authBaseUrl?: string, file?: string): unknown;
46
+ //# sourceMappingURL=account-session.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"account-session.d.ts","sourceRoot":"","sources":["../src/account-session.ts"],"names":[],"mappings":"AAqBA,OAAO,EACL,eAAe,EAWhB,MAAM,gBAAgB,CAAC;AAExB,iHAAiH;AACjH,MAAM,MAAM,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAuE3E;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,eAA6B,EACnC,WAAW,GAAE,MAA4B,EACzC,IAAI,SAAwB,GAC3B,MAAM,GAAG,SAAS,CAkBpB;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,WAAW,GAAE,MAA4B,EAAE,IAAI,SAAwB,GAAG,OAAO,CAErH;AAwDD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,GAAE,eAA6B,EACnC,WAAW,GAAE,MAA4B,EACzC,IAAI,SAAwB,GAC3B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoB7B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,GAAE,eAA6B,EACnC,aAAa,GAAE,MAAwC,EACvD,WAAW,GAAE,MAA4B,EACzC,IAAI,SAAwB,GAC3B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAqB7B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAcjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EAC5B,IAAI,GAAE,eAA6B,EACnC,WAAW,GAAE,MAA4B,EACzC,IAAI,SAAwB,GAC3B,OAAO,CAIT"}
@@ -0,0 +1,262 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.keepAccountSession = keepAccountSession;
4
+ exports.forgetAccountSession = forgetAccountSession;
5
+ exports.accountSessionToken = accountSessionToken;
6
+ exports.localSignInToken = localSignInToken;
7
+ exports.signedInAnswer = signedInAnswer;
8
+ exports.keepSignIn = keepSignIn;
9
+ /**
10
+ * The sign-in the local (stdio) server keeps after the account tools.
11
+ *
12
+ * didit_account_verify_email, didit_account_login and didit_account_verify_2fa answer with an
13
+ * access token. The server used to hand it to the model and forget it, so the very next tool
14
+ * call was unauthenticated: an agent that had just created an account could not create a
15
+ * workflow without restarting the server with DIDIT_ACCESS_TOKEN set. The server now keeps the
16
+ * sign-in the way it keeps a device-code one (device-login.ts): in the same credentials file,
17
+ * readable by the person only, and refreshed before it expires.
18
+ *
19
+ * - It is stored under the auth service's address; a device-code sign-in is stored under the
20
+ * console's. Neither overwrites the other, and the local server uses whichever is newer.
21
+ * - The refresh token never leaves this module. The auth service rotates it on every use and
22
+ * ends the session when an old one is presented again, so a copy in the model's hands would
23
+ * be a way to sign the server out by accident. The tools' answers no longer carry it.
24
+ * - When the credentials file cannot be written (a read-only home directory in a container),
25
+ * the sign-in is kept in memory for the life of the process instead.
26
+ *
27
+ * A token (access or refresh) is never logged, printed or put in an error message.
28
+ */
29
+ const config_1 = require("./config");
30
+ const device_login_1 = require("./device-login");
31
+ /** The key of an account-tools sign-in in the credentials file. */
32
+ const storeKey = (authBaseUrl) => (0, device_login_1.normalizeOrigin)(authBaseUrl);
33
+ /**
34
+ * The file is the store. This holds what the file could not be made to say: a sign-in whose
35
+ * write failed, or `null` for a sign-in that ended while the file could not be updated. An entry
36
+ * here is always newer than the file, so it wins: otherwise a file that turned read-only would
37
+ * keep the server acting as the account that was signed in before. Kept per credentials file
38
+ * and auth address, and dropped as soon as the file can be written again.
39
+ */
40
+ const unsaved = new Map();
41
+ const unsavedKey = (authBaseUrl, file) => `${file}\n${storeKey(authBaseUrl)}`;
42
+ /** The claims of a JWT, unverified: only to read which client the token was issued to. */
43
+ function claimsOf(token) {
44
+ try {
45
+ const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
46
+ return payload && typeof payload === "object" ? payload : {};
47
+ }
48
+ catch {
49
+ return {};
50
+ }
51
+ }
52
+ function load(authBaseUrl, file) {
53
+ const key = unsavedKey(authBaseUrl, file);
54
+ if (unsaved.has(key))
55
+ return unsaved.get(key) ?? undefined;
56
+ return (0, device_login_1.loadCredentials)(storeKey(authBaseUrl), file);
57
+ }
58
+ function store(authBaseUrl, session, file) {
59
+ const key = unsavedKey(authBaseUrl, file);
60
+ try {
61
+ (0, device_login_1.saveCredentials)(storeKey(authBaseUrl), session, file);
62
+ unsaved.delete(key);
63
+ return { where: "file", path: file };
64
+ }
65
+ catch {
66
+ // A home directory that cannot be written must not cost the sign-in.
67
+ unsaved.set(key, session);
68
+ return { where: "memory" };
69
+ }
70
+ }
71
+ function forget(authBaseUrl, file) {
72
+ const key = unsavedKey(authBaseUrl, file);
73
+ const had = load(authBaseUrl, file) !== undefined;
74
+ try {
75
+ (0, device_login_1.deleteCredentials)(storeKey(authBaseUrl), file);
76
+ }
77
+ catch {
78
+ // Checked below: what matters is what the file says now, not how the delete failed.
79
+ }
80
+ // A delete can fail without throwing (the last entry is removed by unlinking the file, and
81
+ // that error is swallowed), so read the file back. If it still holds the sign-in, remember
82
+ // here that it is over.
83
+ let stillInFile = true;
84
+ try {
85
+ stillInFile = (0, device_login_1.loadCredentials)(storeKey(authBaseUrl), file) !== undefined;
86
+ }
87
+ catch {
88
+ // Unreadable: nothing can be loaded from it either, but stay on the safe side.
89
+ }
90
+ if (stillInFile)
91
+ unsaved.set(key, null);
92
+ else
93
+ unsaved.delete(key);
94
+ return had;
95
+ }
96
+ /**
97
+ * Keep the sign-in an account tool just returned. `tokens` is the auth service's answer
98
+ * (`access_token`, `refresh_token`, `expires_in`); anything without an access token (a second
99
+ * factor step, an SSO notice) keeps nothing and returns undefined.
100
+ */
101
+ function keepAccountSession(tokens, deps = device_login_1.defaultDeps, authBaseUrl = config_1.DIDIT_AUTH_BASE_URL, file = (0, device_login_1.credentialsFilePath)()) {
102
+ const answer = (tokens && typeof tokens === "object" ? tokens : {});
103
+ if (typeof answer.access_token !== "string" || !answer.access_token)
104
+ return undefined;
105
+ const claims = claimsOf(answer.access_token);
106
+ const clientId = typeof claims.client_id === "string" ? claims.client_id : typeof claims.aud === "string" ? claims.aud : "";
107
+ const lifetime = Number(answer.expires_in) > 0 ? Number(answer.expires_in) : 3600;
108
+ return store(authBaseUrl, {
109
+ client_id: clientId,
110
+ access_token: answer.access_token,
111
+ ...(typeof answer.refresh_token === "string" && answer.refresh_token ? { refresh_token: answer.refresh_token } : {}),
112
+ expires_at: deps.now() + lifetime * 1000,
113
+ signed_in_at: deps.now(),
114
+ }, file);
115
+ }
116
+ /** Remove the kept account-tools sign-in from this machine. Returns whether there was one. */
117
+ function forgetAccountSession(authBaseUrl = config_1.DIDIT_AUTH_BASE_URL, file = (0, device_login_1.credentialsFilePath)()) {
118
+ return forget(authBaseUrl, file);
119
+ }
120
+ const inFlightRefreshes = new Map();
121
+ const SIGN_IN_AGAIN = "Your Didit sign-in expired or was ended. Sign in again with didit_account_login (or run `didit-mcp-server login`).";
122
+ async function refresh(deps, authBaseUrl, file) {
123
+ // Re-read: another process sharing the file may have rotated the pair while this one waited.
124
+ const current = load(authBaseUrl, file);
125
+ if (!current?.access_token)
126
+ throw new device_login_1.DeviceLoginError("login_required", SIGN_IN_AGAIN);
127
+ if ((current.expires_at ?? 0) - deps.now() > device_login_1.REFRESH_SKEW_MS)
128
+ return current;
129
+ if (!current.refresh_token || !current.client_id) {
130
+ forget(authBaseUrl, file);
131
+ throw new device_login_1.DeviceLoginError("login_required", SIGN_IN_AGAIN);
132
+ }
133
+ let res;
134
+ try {
135
+ // service-didit-auth `/token/`: a JSON body, and the client the token was issued to.
136
+ res = await deps.fetch(`${(0, device_login_1.normalizeOrigin)(authBaseUrl)}/token/`, {
137
+ method: "POST",
138
+ headers: { "Content-Type": "application/json", Accept: "application/json" },
139
+ body: JSON.stringify({ grant_type: "refresh_token", refresh_token: current.refresh_token, client_id: current.client_id }),
140
+ });
141
+ }
142
+ catch {
143
+ // A network failure says nothing about the session: keep it and try again on the next call.
144
+ throw new device_login_1.DeviceLoginError("temporarily_unavailable", "Could not reach Didit to refresh the sign-in.");
145
+ }
146
+ let body = {};
147
+ try {
148
+ body = await res.json();
149
+ }
150
+ catch {
151
+ // A body that is not JSON is handled by the status below.
152
+ }
153
+ if (res.ok && typeof body?.access_token === "string" && body.access_token) {
154
+ const next = {
155
+ client_id: current.client_id,
156
+ access_token: body.access_token,
157
+ // The auth service rotates the refresh token on every use: always keep the new one.
158
+ refresh_token: typeof body.refresh_token === "string" && body.refresh_token ? body.refresh_token : current.refresh_token,
159
+ expires_at: deps.now() + (Number(body.expires_in) > 0 ? Number(body.expires_in) : 3600) * 1000,
160
+ signed_in_at: current.signed_in_at,
161
+ };
162
+ store(authBaseUrl, next, file);
163
+ return next;
164
+ }
165
+ if (res.status === 400 || res.status === 401 || res.status === 403) {
166
+ // The session is over (expired, ended from the console, or its refresh token was used elsewhere).
167
+ forget(authBaseUrl, file);
168
+ throw new device_login_1.DeviceLoginError("login_required", SIGN_IN_AGAIN);
169
+ }
170
+ throw new device_login_1.DeviceLoginError("temporarily_unavailable", `Could not refresh the Didit sign-in (HTTP ${res.status}).`);
171
+ }
172
+ /**
173
+ * The kept account-tools access token, refreshed when it expires within 60 s. Concurrent callers
174
+ * share one refresh (a refresh token works once). Returns undefined when nothing is kept; throws
175
+ * login_required when the session is over.
176
+ */
177
+ async function accountSessionToken(deps = device_login_1.defaultDeps, authBaseUrl = config_1.DIDIT_AUTH_BASE_URL, file = (0, device_login_1.credentialsFilePath)()) {
178
+ const kept = load(authBaseUrl, file);
179
+ if (!kept?.access_token)
180
+ return undefined;
181
+ if ((kept.expires_at ?? 0) - deps.now() > device_login_1.REFRESH_SKEW_MS)
182
+ return kept.access_token;
183
+ const key = `${file}\n${storeKey(authBaseUrl)}`;
184
+ let job = inFlightRefreshes.get(key);
185
+ if (!job) {
186
+ job = refresh(deps, authBaseUrl, file).finally(() => inFlightRefreshes.delete(key));
187
+ inFlightRefreshes.set(key, job);
188
+ }
189
+ try {
190
+ return (await job).access_token;
191
+ }
192
+ catch (error) {
193
+ // A transient outage must not drop a token that still works for a few more seconds.
194
+ if (error instanceof device_login_1.DeviceLoginError && error.code === "temporarily_unavailable" && (kept.expires_at ?? 0) > deps.now()) {
195
+ return kept.access_token;
196
+ }
197
+ throw error;
198
+ }
199
+ }
200
+ /**
201
+ * The access token of the local server's sign-in: the device-code one or the account-tools one,
202
+ * whichever the person did last. Returns undefined when neither exists.
203
+ */
204
+ async function localSignInToken(deps = device_login_1.defaultDeps, consoleOrigin = config_1.MCP_AUTHORIZATION_SERVER_ORIGIN, authBaseUrl = config_1.DIDIT_AUTH_BASE_URL, file = (0, device_login_1.credentialsFilePath)()) {
205
+ const device = (0, device_login_1.loadCredentials)(consoleOrigin, file);
206
+ const account = load(authBaseUrl, file);
207
+ const deviceToken = () => (0, device_login_1.getStoredAccessToken)(deps, consoleOrigin, file);
208
+ const accountToken = () => accountSessionToken(deps, authBaseUrl, file);
209
+ // A device-code entry without a refresh token is only a remembered client, not a sign-in.
210
+ if (!device?.refresh_token)
211
+ return accountToken();
212
+ if (!account?.access_token)
213
+ return deviceToken();
214
+ const accountIsNewer = (account.signed_in_at ?? 0) >= (device.signed_in_at ?? 0);
215
+ const [newer, older] = accountIsNewer ? [accountToken, deviceToken] : [deviceToken, accountToken];
216
+ try {
217
+ return await newer();
218
+ }
219
+ catch (error) {
220
+ // The newer sign-in is over (and was removed by its own refresh): the older one still stands.
221
+ if (!(error instanceof device_login_1.DeviceLoginError) || error.code !== "login_required")
222
+ throw error;
223
+ const fallback = await older();
224
+ if (fallback === undefined)
225
+ throw error;
226
+ return fallback;
227
+ }
228
+ }
229
+ /**
230
+ * What an account tool answers once the server kept its sign-in: the same answer without the
231
+ * refresh token, and a line saying the next tools are authenticated. Answers that carry no
232
+ * access token (a second factor step, an SSO notice) pass through unchanged.
233
+ */
234
+ function signedInAnswer(answer, kept) {
235
+ if (!kept || !answer || typeof answer !== "object")
236
+ return answer;
237
+ const { refresh_token: _refreshToken, ...rest } = answer;
238
+ return {
239
+ ...rest,
240
+ signed_in: true,
241
+ next_step: (kept.where === "file"
242
+ ? `Signed in. The local server keeps this sign-in in ${kept.path} (readable by you only) and refreshes it, `
243
+ : "Signed in. The credentials file could not be written, so the local server keeps this sign-in in memory until it stops, ") +
244
+ "so the tools that follow are authenticated: do not pass access_token to them. Call didit_context_get for the " +
245
+ "organization and its applications (each application's mode is live or sandbox).",
246
+ };
247
+ }
248
+ /**
249
+ * What the server does with an account tool's answer: on the local server, keep the sign-in so
250
+ * the next tool is authenticated and take the refresh token out of what the model sees.
251
+ *
252
+ * A hosted server keeps nothing, ever: its process and its credentials file are shared by every
253
+ * caller, so one caller's refresh token must never land there. A hosted server already refuses
254
+ * the account tools before they run (index.ts); this is the same rule stated where the token is
255
+ * stored, so it holds whatever happens to that refusal.
256
+ */
257
+ function keepSignIn(answer, options, deps = device_login_1.defaultDeps, authBaseUrl = config_1.DIDIT_AUTH_BASE_URL, file = (0, device_login_1.credentialsFilePath)()) {
258
+ if (options.hosted)
259
+ return answer;
260
+ return signedInAnswer(answer, keepAccountSession(answer, deps, authBaseUrl, file));
261
+ }
262
+ //# sourceMappingURL=account-session.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"account-session.js","sourceRoot":"","sources":["../src/account-session.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,77 @@
1
+ /**
2
+ * API key connections: a hosted connection that authenticates with an application API key
3
+ * instead of a person's sign-in.
4
+ *
5
+ * Why: an agent that runs with no person present (CI, a scheduled job, a backend agent) has no
6
+ * browser to finish an OAuth sign-in in, and a person's access token lasts a day. It already
7
+ * holds the credential it sends to the Didit API, so the hosted server takes that one:
8
+ *
9
+ * Authorization: Bearer <api key> or x-api-key: <api key>
10
+ *
11
+ * on `/mcp` and `/mcp/payments`. Nothing changes for a client that signs in with OAuth.
12
+ *
13
+ * What such a connection is: ONE application. The key is forwarded to the Didit API as
14
+ * `x-api-key`, and the API decides what it may do, exactly as on a direct API call: a
15
+ * full-access key reaches every route of its own application, a restricted key the resources it
16
+ * was given (service-didit-verification `core/api_key_access.py`). Nothing here grants anything.
17
+ *
18
+ * What it is not: a person. Tools that act for a member of an organization (members, roles, API
19
+ * key management, plans, cards, receipts) are neither listed nor run on it, and neither are the
20
+ * download links, which carry the caller's credential inside the link.
21
+ */
22
+ import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
23
+ /** The application an API key belongs to: everything its connection can act on. */
24
+ export interface ApiKeyScope {
25
+ organizationId: string;
26
+ organizationName?: string;
27
+ applicationId: string;
28
+ applicationName?: string;
29
+ /** "live" | "sandbox", as the auth service reports it. */
30
+ mode?: string;
31
+ /** A named key's id. The application's primary key has none. */
32
+ keyId?: string;
33
+ /** The key's label and display prefix as the console shows them (never the key). */
34
+ keyLabel?: string;
35
+ keyPrefix?: string;
36
+ /** True for the application's primary key. */
37
+ primary: boolean;
38
+ /** True when the key is limited to some resources; false for a full-access key. */
39
+ restricted: boolean;
40
+ }
41
+ /**
42
+ * A Didit access token is a JWT (three dot-separated parts). An API key is URL-safe random text,
43
+ * with or without the `sk_live_` / `sk_test_` marker, and never contains a dot. So the shape
44
+ * alone tells them apart, and each credential costs exactly one introspection.
45
+ */
46
+ export declare function looksLikeApiKey(credential: string): boolean;
47
+ /**
48
+ * The AuthInfo of an accepted API key, from the auth service's introspection answer
49
+ * (service-didit-auth `TokenProcessor.verify_api_key`): `sub` is the application, and `api_key`
50
+ * carries the key's own limits.
51
+ *
52
+ * `scopes` is empty on purpose. The permission pre-check (permissions.ts) compares a person's
53
+ * role permissions; a key has none, and the API enforces the key's own access on every call.
54
+ */
55
+ export declare function apiKeyAuthInfo(key: string, data: Record<string, unknown>, resource: URL, now?: number): AuthInfo;
56
+ /** The application behind the connection when it authenticated with an API key; undefined for a person's sign-in. */
57
+ export declare function apiKeyScopeOf(authInfo: AuthInfo | undefined): ApiKeyScope | undefined;
58
+ /**
59
+ * Tools an API key connection neither lists nor runs.
60
+ *
61
+ * All but the last group act for a MEMBER of an organization, on routes the auth service and the
62
+ * console API only open to a person's sign-in (an application credential is refused there). The
63
+ * list was checked against the API with a real key: every read-only tool that takes no argument
64
+ * was called through an API key connection, and the ones refused by design are here. The download
65
+ * links seal the caller's credential inside the link; a person's token inside one stops working
66
+ * within a day, a key would not.
67
+ */
68
+ export declare const PERSON_ONLY_TOOLS: ReadonlySet<string>;
69
+ /** Why a person-only tool does not run on an API key connection, and what to do instead. */
70
+ export declare function personOnlyRefusal(name: string): string;
71
+ /** Why a call that names another organization or application is refused, or undefined when it may proceed. */
72
+ export declare function apiKeyScopeRefusal(scope: ApiKeyScope, organizationId: string | undefined, applicationId: string | undefined): string | undefined;
73
+ /** The key's organization, as `didit_org_list` answers for a person. */
74
+ export declare function apiKeyOrganizations(scope: ApiKeyScope): Record<string, unknown>[];
75
+ /** The key's application, as `didit_org_list_applications` and `didit_org_get_application` answer for a person. */
76
+ export declare function apiKeyApplication(scope: ApiKeyScope): Record<string, unknown>;
77
+ //# sourceMappingURL=api-key-connection.d.ts.map