toolkits/endpoints.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137


Toolkit Endpoints
back to toolkits /// home
Custom API routes defined by toolkits. These live under /tk/app/{toolkit}/ or /tk/lib/{toolkit}/ depending on the toolkit type.
Route format
POST /tk/app/beepzone/kiosk/scan
GET  /tk/lib/opensigma/status


The path after the toolkit name is matched against endpoint definitions in the toolkit config.
Endpoint types
Internal
Runs logic within the server process. Can use pseudo_querys to execute database queries based on the request payload. No external service needed.
HTTP
Proxies the request to an external HTTP service. The server wraps the payload in a context object (user info, DB context etc), sends it to the upstream URL and returns the response.
Can return JSON (wrapped in the standard envelope) or passthrough (raw bytes with the upstream content type, useful for file downloads).
Executable
Runs a shell command on the server. The request context is passed as a JSON string argument. Output is parsed as JSON or wrapped in { "output": "..." } if its not valid JSON.
Request flow

verify the toolkit exists and is enabled (404 if not)
match the endpoint path in config (404 if not found)
check endpoint level permissions for your power level (403 if denied)
validate payload against client_filter rules (400 if invalid)
fetch inject_db_context values from the database
resolve your toolkit group
build the request context
apply overwrite_wrapping transformations
execute based on endpoint type

Request context
The context object sent to backends looks like this:
{
  "user_id": 1,
  "username": "admin",
  "power": 100,
  "core_group_id": 1,
  "core_group_name": "administrators",
  "toolkit_group": "managers",
  "request_id": "abc123",
  "payload": { ... },
  "db_context": { "key": "value" }
}


toolkit_group is the users group within this specific toolkit (resolved via jde_associations or toolkit_overrides).
db_context contains values fetched via inject_db_context config.
Client filter
Validates the incoming request payload before anything else happens.
[endpoints.0.client_filter]
allowed_fields = ["barcode", "quantity"]
required_fields = ["barcode"]
max_body_bytes = 4096


Field
Notes


allowed_fields
only these fields are accepted, everything else gets stripped


required_fields
these must be present or you get 400


max_body_bytes
max payload size


allowed_content_types
restrict accepted content types


field_rules
per field validation (type, max_length, pattern, allowed_values)


Per field rules example:
[endpoints.0.client_filter.field_rules.barcode]
type = "string"
max_length = 50
pattern = "^[A-Z0-9-]+$"


Database context injection
inject_db_context lets you pull values from the database and include them in the request context.
Simple: pull a value by column name
inject_db_context = ["users.email"]


Filtered: pull specific rows based on payload values
inject_db_context = ["items.name?id=$payload.item_id"]


The $payload.field syntax references fields from the clients request body.
Overwrite wrapping
Modify the context envelope before sending it to the backend.

prefix with - to remove a field: "-power" removes the power level from context
without prefix: promotes a db_context value to a top level field

Success response
{
  "success": true,
  "request_id": "abc123",
  "endpoint": "/tk/app/beepzone/kiosk/scan",
  "data": { ... }
}


Error responses


Code
When


400
payload validation failed


401
no token or invalid session


403
endpoint permission denied


404
toolkit not found/disabled, endpoint path doesnt exist


500
internal error, DB context fetch failed, executable error


502
HTTP upstream returned an error