Docs: examples for using Credentials with $curl

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'
 ```

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.

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

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": [

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