From 2bbce763f02aa9681733aeaf8dbb67eec7d43372 Mon Sep 17 00:00:00 2001 From: Andreas Eberhart Date: Fri, 13 Nov 2026 17:08:30 +0100 Subject: [PATCH 1/2] Docs: examples for using Credentials with $curl Add jsonata.json examples for basic auth, API key and dj-insert-credentials, and document them in the developer and JSONata references. #531 Co-Authored-By: Claude Opus 5.5 --- dashjoin-docs/docs/developer-reference.md | 30 +++++++++++++++++++++++ dashjoin-docs/docs/jsonata-reference.md | 2 +- dashjoin-docs/llms/jsonata.json | 16 ++++++++++++ 3 files changed, 47 insertions(+), 1 deletion(-) diff --git a/dashjoin-docs/docs/developer-reference.md b/dashjoin-docs/docs/developer-reference.md index ec552540e..204b373d3 100644 --- a/dashjoin-docs/docs/developer-reference.md +++ b/dashjoin-docs/docs/developer-reference.md @@ -148,6 +148,36 @@ Configuration: * password: credential password * apiKey: if true, use username / password as another header - this feature can be used to pass API keys etc. while not having to show the key in plain text in the header input form. If this value is omitted or false, username and password are converted to a basic authentication header +Examples: + +Basic authentication: create a Credentials function with ID "dashjoin", username "admin" and password "djdjdj". +The call below sends the header "Authorization: Basic YWRtaW46ZGpkamRq": + +``` +$curl("GET", "http://localhost:8080/rest/manage/version", null, {"Authorization": "dashjoin"}) +``` + +Bearer token / API key: create a Credentials function with ID "openai", username "Authorization", +password "Bearer sk-..." and apiKey set to true. The header named by username is set to the password: + +``` +$curl("GET", "https://api.openai.com/v1/models", null, {"Authorization": "openai"}) +``` + +If the service expects the key in a different header (e.g. "X-API-Key: ..."), set username to "X-API-Key". +The Authorization header is still used to reference the credential, but it is removed before the request is sent, +so the call above sends only "X-API-Key: ...". + +Secrets in the request body: some services expect the secret in the payload (e.g. a login form). +Use the header "dj-insert-credentials" to list the fields of the data object (a single field name or an array) +whose value is the ID of a Credentials function. The value is replaced with the password (apiKey = true) or the basic authentication value (apiKey omitted or false): + +``` +$curl("POST", "https://example.com/api/login", {"user": "admin", "password": "exampleLogin"}, {"dj-insert-credentials": ["password"]}) +``` + +Users must have one of the roles of the Credentials function in order to use it (admin only if it has no roles). + ### MCPServer Allows configuring an external MCP server. Tools offered by this server can be attached to AIApp. diff --git a/dashjoin-docs/docs/jsonata-reference.md b/dashjoin-docs/docs/jsonata-reference.md index a1c1a17df..d0e1a14ba 100644 --- a/dashjoin-docs/docs/jsonata-reference.md +++ b/dashjoin-docs/docs/jsonata-reference.md @@ -48,7 +48,7 @@ chat | $chat(url, query, messages, tools?, options?, headers?) | Encapsulates AP classifyEntities | $classifyEntities([entities], entity-language?, limit?, subclass-depth?) | Reconciles entities and finds common classifications that all entities are an instance of. The parameters are similar to the reconcileEntity function. The subclass depth (default 1) describes the number of superclasses that are included in the results (see [AI & ML Integration](ai-ml-integration.md)) collectMetadata | $collectMetadata(id) | Reconnects database with id and updates and schema changes create| $create(database, table, object) | ID of the new record -curl | $curl(method, url, data?, headers?) | Full fledged HTTP client. Use header {"Authorization": credential} to reference a credential set defined in functions. Use header {"dj-timeout-seconds": ...} to define a HTTP timeout other than the default of 10s. Use header {"dj-encoding": ...} to encode in UTF_8 (default), BASE_64, ISO_8859_1. Use header {"dj-produces": "text/plain"} to return plain text rather than JSON. Use header {"Content-Type": "multipart/form-data"} to upload files encoded in data URLs in the data object (see Input widget) +curl | $curl(method, url, data?, headers?) | Full fledged HTTP client. Use header {"Authorization": credential} to reference a credential set defined in functions (e.g. $curl("GET", url, null, {"Authorization": "openai"})). Use header {"dj-insert-credentials": [field, ...]} to replace the values of these fields in data (which contain credential names) with the credential secret. Use header {"dj-timeout-seconds": ...} to define a HTTP timeout other than the default of 10s. Use header {"dj-encoding": ...} to encode in UTF_8 (default), BASE_64, ISO_8859_1. Use header {"dj-produces": "text/plain"} to return plain text rather than JSON. Use header {"Content-Type": "multipart/form-data"} to upload files encoded in data URLs in the data object (see Input widget) delete| $delete(database, table, pk1) djLint | $djLint() | Scans the app for errors and warnings djRoles | $djRoles() | Returns the roles of the current user diff --git a/dashjoin-docs/llms/jsonata.json b/dashjoin-docs/llms/jsonata.json index 1c49b2ba8..ac8d676b1 100644 --- a/dashjoin-docs/llms/jsonata.json +++ b/dashjoin-docs/llms/jsonata.json @@ -311,6 +311,22 @@ "vendor": "Dashjoin", "name": "Dashjoin Low Code Development and Integration Platform" } + }, + { + "description": "open the HTTP GET service at the given URL using the Credentials function 'dashjoin' (username / password, apiKey omitted or false). Instead of a literal header value, the Authorization header is set to the ID of the Credentials function. The platform replaces it with a basic authentication header computed from the stored username and password, so the password never appears in the expression", + "code": "$curl('GET', 'http://localhost:8080/rest/manage/version', null, {'Authorization': 'dashjoin'})", + "output": { + "vendor": "Dashjoin", + "name": "Dashjoin Low Code Development and Integration Platform" + } + }, + { + "description": "call an API that expects an API key using the Credentials function 'openai' with apiKey=true, username='Authorization' and password='Bearer sk-...'. With apiKey=true, the header named by username is set to the password value. Use e.g. username='X-API-Key' for services that expect the key in a different header. The Authorization header is always used to reference the Credentials function by ID. It is removed before the request is sent if username is a different header", + "code": "$curl('GET', 'https://api.openai.com/v1/models', null, {'Authorization': 'openai'})" + }, + { + "description": "POST a login form where the secret must be part of the request body rather than a header. The header dj-insert-credentials lists the fields of data (single name or array) whose value is the ID of a Credentials function. These values are replaced with the stored password (apiKey=true) or a basic authentication value (apiKey false)", + "code": "$curl('POST', 'https://example.com/api/login', {'user': 'admin', 'password': 'exampleLogin'}, {'dj-insert-credentials': ['password']})" } ], "chat": [ From 9a3e5f14e3b15dc67674bb000677b5ad4ebe9ef9 Mon Sep 17 00:00:00 2001 From: Andreas Eberhart Date: Fri, 13 Nov 2026 17:10:59 +0100 Subject: [PATCH 2/2] Docs: regenerate appendix-jsonata.md and llms.txt Picks up the new $curl credential examples from jsonata.json. #531 Co-Authored-By: Claude Opus 5.5 --- dashjoin-docs/docs/appendix-jsonata.md | 30 ++++++++++++++++++++++++++ llms.txt | 15 +++++++++++++ 2 files changed, 45 insertions(+) diff --git a/dashjoin-docs/docs/appendix-jsonata.md b/dashjoin-docs/docs/appendix-jsonata.md index 5050d5fba..b0ed65c2f 100644 --- a/dashjoin-docs/docs/appendix-jsonata.md +++ b/dashjoin-docs/docs/appendix-jsonata.md @@ -328,6 +328,36 @@ Sample output: "name" : "Dashjoin Low Code Development and Integration Platform" } ``` +### curl +open the HTTP GET service at the given URL using the Credentials function 'dashjoin' (username / password, apiKey omitted or false). Instead of a literal header value, the Authorization header is set to the ID of the Credentials function. The platform replaces it with a basic authentication header computed from the stored username and password, so the password never appears in the expression +``` +$curl('GET', 'http://localhost:8080/rest/manage/version', null, {'Authorization': 'dashjoin'}) +``` +Sample output: +```json +{ + "vendor" : "Dashjoin", + "name" : "Dashjoin Low Code Development and Integration Platform" +} +``` +### curl +call an API that expects an API key using the Credentials function 'openai' with apiKey=true, username='Authorization' and password='Bearer sk-...'. With apiKey=true, the header named by username is set to the password value. Use e.g. username='X-API-Key' for services that expect the key in a different header. The Authorization header is always used to reference the Credentials function by ID. It is removed before the request is sent if username is a different header +``` +$curl('GET', 'https://api.openai.com/v1/models', null, {'Authorization': 'openai'}) +``` +Sample output: +```json +null +``` +### curl +POST a login form where the secret must be part of the request body rather than a header. The header dj-insert-credentials lists the fields of data (single name or array) whose value is the ID of a Credentials function. These values are replaced with the stored password (apiKey=true) or a basic authentication value (apiKey false) +``` +$curl('POST', 'https://example.com/api/login', {'user': 'admin', 'password': 'exampleLogin'}, {'dj-insert-credentials': ['password']}) +``` +Sample output: +```json +null +``` ### delete delete REQUEST 7 in the database 'sqlite' ``` diff --git a/llms.txt b/llms.txt index 1e5c4efa4..26b589210 100644 --- a/llms.txt +++ b/llms.txt @@ -1583,6 +1583,21 @@ DESCRIPTION: open the HTTP GET service at the given URL and pass the authorizati LANGUAGE: jsonata CODE: $curl('GET', 'http://localhost:8080/rest/manage/version', null, {'Authorization': 'Basic YWRtaW46ZGpkamRq'}) +TITLE: curl +DESCRIPTION: open the HTTP GET service at the given URL using the Credentials function 'dashjoin' (username / password, apiKey omitted or false). Instead of a literal header value, the Authorization header is set to the ID of the Credentials function. The platform replaces it with a basic authentication header computed from the stored username and password, so the password never appears in the expression +LANGUAGE: jsonata +CODE: $curl('GET', 'http://localhost:8080/rest/manage/version', null, {'Authorization': 'dashjoin'}) + +TITLE: curl +DESCRIPTION: call an API that expects an API key using the Credentials function 'openai' with apiKey=true, username='Authorization' and password='Bearer sk-...'. With apiKey=true, the header named by username is set to the password value. Use e.g. username='X-API-Key' for services that expect the key in a different header. The Authorization header is always used to reference the Credentials function by ID. It is removed before the request is sent if username is a different header +LANGUAGE: jsonata +CODE: $curl('GET', 'https://api.openai.com/v1/models', null, {'Authorization': 'openai'}) + +TITLE: curl +DESCRIPTION: POST a login form where the secret must be part of the request body rather than a header. The header dj-insert-credentials lists the fields of data (single name or array) whose value is the ID of a Credentials function. These values are replaced with the stored password (apiKey=true) or a basic authentication value (apiKey false) +LANGUAGE: jsonata +CODE: $curl('POST', 'https://example.com/api/login', {'user': 'admin', 'password': 'exampleLogin'}, {'dj-insert-credentials': ['password']}) + TITLE: chat DESCRIPTION: Call the LLM comlpetion API of OpenAI with the query 'hi', the system prompt 'be funny', and the 'openai' credential LANGUAGE: jsonata