@cosmicdrift/kumiko-samples 0.410.0 → 0.412.0
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.
- package/package.json +1 -1
- package/packages/bundled-features/package.json +31 -1
- package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
- package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
- package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
- package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
- package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
- package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
- package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
- package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
- package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
- package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
- package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
- package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
- package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
- package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
- package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
- package/packages/bundled-features/src/agent-tools/changes.json +24 -0
- package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
- package/packages/bundled-features/src/agent-tools/index.ts +24 -0
- package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
- package/packages/bundled-features/src/auth-email-password/changes.json +24 -0
- package/packages/bundled-features/src/auth-email-password/seeding.ts +84 -6
- package/packages/bundled-features/src/auth-email-password/web/i18n.ts +1 -0
- package/packages/bundled-features/src/auth-email-password/web/signup-screen.tsx +48 -3
- package/packages/bundled-features/src/auth-email-password/web/static-account.ts +190 -0
- package/packages/bundled-features/src/auth-email-password/web/static-client.ts +226 -0
- package/packages/bundled-features/src/foundation-shared/demo-admin-env.ts +11 -0
- package/packages/bundled-features/src/foundation-shared/index.ts +5 -1
- package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
- package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
- package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
- package/packages/bundled-features/src/inbound-provider-imap/changes.json +6 -0
- package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts +3 -1
- package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
- package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
- package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
- package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
- package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
- package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
- package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
- package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
- package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
- package/packages/bundled-features/src/presence/changes.json +8 -0
- package/packages/bundled-features/src/presence/feature.ts +25 -0
- package/packages/bundled-features/src/presence/handlers/heartbeat.write.ts +52 -0
- package/packages/bundled-features/src/presence/handlers/leave.write.ts +41 -0
- package/packages/bundled-features/src/presence/handlers/list.query.ts +39 -0
- package/packages/bundled-features/src/presence/index.ts +7 -0
- package/packages/bundled-features/src/presence/options.ts +30 -0
- package/packages/bundled-features/src/presence/payloads.ts +26 -0
- package/packages/bundled-features/src/presence/room.ts +65 -0
- package/packages/bundled-features/src/presence/store.ts +185 -0
- package/packages/bundled-features/src/sessions/feature.ts +6 -2
- package/packages/bundled-features/src/sessions/handlers/last-activity-probe.route.ts +19 -0
- package/packages/bundled-features/src/tenant-inactivity/changes.json +12 -0
- package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +14 -6
- package/packages/bundled-features/src/tenant-inactivity/constants.ts +4 -1
- package/packages/bundled-features/src/tenant-inactivity/handlers/inactivity-state.query.ts +2 -1
- package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +2 -1
- package/packages/bundled-features/src/tenant-inactivity/options.ts +1 -0
- package/packages/bundled-features/src/tenant-inactivity/remote-activity.ts +6 -1
- package/packages/bundled-features/src/tenant-inactivity/static-keep-account.ts +37 -0
- package/packages/bundled-features/src/tenant-lifecycle/constants.ts +2 -0
- package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts +6 -2
- package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts +2 -1
- package/packages/bundled-features/src/tenant-lifecycle/index.ts +1 -0
- package/packages/bundled-features/src/waitlist/changes.json +6 -0
- package/packages/bundled-features/src/waitlist/static-submit.ts +56 -0
- package/samples/apps/styleguide/src/features/widgets/i18n.ts +143 -0
- package/samples/apps/styleguide/src/features/widgets/web/VariantsDemo.tsx +276 -0
- package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx +3 -0
- package/samples/apps/styleguide/src/features/workboard/feature.ts +1 -0
- package/samples/apps/use-all-bundled/feature-manifest.json +23 -1
- package/samples/apps/use-all-bundled/src/run-config.ts +3 -0
- package/samples/recipes/api-docs/README.md +52 -0
- package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/index.json +371 -0
- package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
- package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
- package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
- package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
- package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
- package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
- package/samples/recipes/api-docs/kumiko.config.ts +33 -0
- package/samples/recipes/api-docs/package.json +14 -0
- package/samples/recipes/api-docs/src/feature.ts +218 -0
- package/samples/recipes/api-docs/tsconfig.json +22 -0
- package/samples/recipes/realtime-sse/README.md +1 -0
- package/samples/recipes/realtime-sse/package.json +1 -0
- package/samples/recipes/realtime-sse/src/feature.ts +9 -0
- package/samples/recipes/record-detail-layout/README.md +1 -0
- package/samples/recipes/record-detail-layout/src/feature.ts +10 -0
- package/samples/recipes/wizard-form/README.md +9 -0
- package/samples/recipes/wizard-form/src/feature.ts +13 -2
|
@@ -0,0 +1,305 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Tickets"
|
|
3
|
+
description: "API reference for Tickets: every handler with its fields and an example."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
### ticket: detail
|
|
7
|
+
|
|
8
|
+
**Show ticket**
|
|
9
|
+
|
|
10
|
+
Returns one ticket.
|
|
11
|
+
|
|
12
|
+
- Required scope: `tickets:read`
|
|
13
|
+
- Endpoint: `POST /api/query`
|
|
14
|
+
|
|
15
|
+
| Field | Type | Required | Description |
|
|
16
|
+
| --- | --- | --- | --- |
|
|
17
|
+
| `id` | string (uuid) | yes | Ticket ID |
|
|
18
|
+
|
|
19
|
+
**Example request**
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
curl -X POST https://helpdesk.example.com/api/query \
|
|
23
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
24
|
+
-H "Content-Type: application/json" \
|
|
25
|
+
-d '{
|
|
26
|
+
"type": "helpdesk:query:ticket:detail",
|
|
27
|
+
"payload": {
|
|
28
|
+
"id": "00000000-0000-4000-8000-000000000001"
|
|
29
|
+
}
|
|
30
|
+
}'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**Example response**
|
|
34
|
+
|
|
35
|
+
Status: 200
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"data": {
|
|
40
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
41
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
42
|
+
"version": 1,
|
|
43
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
44
|
+
"modifiedAt": null,
|
|
45
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
46
|
+
"modifiedById": null,
|
|
47
|
+
"title": "Printer is on fire",
|
|
48
|
+
"status": "open",
|
|
49
|
+
"priority": "high"
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### ticket: list
|
|
55
|
+
|
|
56
|
+
**List tickets**
|
|
57
|
+
|
|
58
|
+
Lists tickets, newest first.
|
|
59
|
+
|
|
60
|
+
- Required scope: `tickets:read`
|
|
61
|
+
- Endpoint: `POST /api/query`
|
|
62
|
+
|
|
63
|
+
| Field | Type | Required | Description |
|
|
64
|
+
| --- | --- | --- | --- |
|
|
65
|
+
| `cursor` | string | no | Position from `nextCursor` of the previous page. |
|
|
66
|
+
| `limit` | integer | no | Rows per page, 50 by default, at most 200. |
|
|
67
|
+
| `search` | string | no | Full-text search across the searchable fields. |
|
|
68
|
+
| `sort` | string | no | Field to sort by. |
|
|
69
|
+
| `sortDirection` | "asc" \| "desc" | no | `asc` or `desc`. |
|
|
70
|
+
| `offset` | integer | no | Number of rows to skip. Prefer `cursor` for paging. |
|
|
71
|
+
| `totalCount` | boolean | no | Set `true` to also get `total`, the number of matching rows. |
|
|
72
|
+
| `includeDeleted` | boolean | no | Set `true` to include deleted rows. Only for entities with soft delete. |
|
|
73
|
+
| `onlyDeleted` | boolean | no | Set `true` to return only deleted rows. Only for entities with soft delete, not together with `includeDeleted`. |
|
|
74
|
+
| `filter` | object | no | One field filter with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
75
|
+
| `filter.field` | string | yes | |
|
|
76
|
+
| `filter.op` | "eq" \| "ne" \| "lt" \| "gt" \| "lte" \| "gte" \| "in" | yes | |
|
|
77
|
+
| `filter.value` | any | yes | |
|
|
78
|
+
| `filters` | array of object | no | Several field filters, each with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
79
|
+
| `namedFilter` | string | no | Name of a predefined filter of the entity, for example a work queue. |
|
|
80
|
+
| `aggregate` | object | no | Returns aggregated values instead of rows. |
|
|
81
|
+
| `aggregate.groupBy` | string | no | |
|
|
82
|
+
| `aggregate.measures` | array of object | no | |
|
|
83
|
+
|
|
84
|
+
**Example request**
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
curl -X POST https://helpdesk.example.com/api/query \
|
|
88
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
89
|
+
-H "Content-Type: application/json" \
|
|
90
|
+
-d '{
|
|
91
|
+
"type": "helpdesk:query:ticket:list",
|
|
92
|
+
"payload": {}
|
|
93
|
+
}'
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**Example response**
|
|
97
|
+
|
|
98
|
+
Status: 200
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"data": {
|
|
103
|
+
"rows": [
|
|
104
|
+
{
|
|
105
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
106
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
107
|
+
"version": 1,
|
|
108
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
109
|
+
"modifiedAt": null,
|
|
110
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
111
|
+
"modifiedById": null,
|
|
112
|
+
"title": "Printer is on fire",
|
|
113
|
+
"status": "open",
|
|
114
|
+
"priority": "high"
|
|
115
|
+
}
|
|
116
|
+
],
|
|
117
|
+
"nextCursor": null
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### ticket: close
|
|
123
|
+
|
|
124
|
+
**Close ticket**
|
|
125
|
+
|
|
126
|
+
Closes a ticket and records how it was resolved.
|
|
127
|
+
|
|
128
|
+
- Required scope: `tickets:write`
|
|
129
|
+
- Endpoint: `POST /api/write`
|
|
130
|
+
|
|
131
|
+
| Field | Type | Required | Description |
|
|
132
|
+
| --- | --- | --- | --- |
|
|
133
|
+
| `id` | string (uuid) | yes | Ticket |
|
|
134
|
+
| `resolution` | string | yes | Resolution |
|
|
135
|
+
|
|
136
|
+
**Example request**
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
curl -X POST https://helpdesk.example.com/api/write \
|
|
140
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
141
|
+
-H "Content-Type: application/json" \
|
|
142
|
+
-d '{
|
|
143
|
+
"type": "helpdesk:write:ticket:close",
|
|
144
|
+
"payload": {
|
|
145
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
146
|
+
"resolution": "Replaced the cartridge"
|
|
147
|
+
}
|
|
148
|
+
}'
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
**Example response**
|
|
152
|
+
|
|
153
|
+
Status: 200
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"isSuccess": true,
|
|
158
|
+
"data": {
|
|
159
|
+
"id": "00000000-0000-4000-8000-000000000001"
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### ticket: create
|
|
165
|
+
|
|
166
|
+
**Create ticket**
|
|
167
|
+
|
|
168
|
+
Opens a new ticket.
|
|
169
|
+
|
|
170
|
+
- Required scope: `tickets:write`
|
|
171
|
+
- Endpoint: `POST /api/write`
|
|
172
|
+
|
|
173
|
+
| Field | Type | Required | Description |
|
|
174
|
+
| --- | --- | --- | --- |
|
|
175
|
+
| `title` | string | yes | Title |
|
|
176
|
+
| `status` | "open" \| "closed" | no | Status |
|
|
177
|
+
| `priority` | "low" \| "normal" \| "high" | no | Priority |
|
|
178
|
+
|
|
179
|
+
**Example request**
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
curl -X POST https://helpdesk.example.com/api/write \
|
|
183
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
184
|
+
-H "Content-Type: application/json" \
|
|
185
|
+
-d '{
|
|
186
|
+
"type": "helpdesk:write:ticket:create",
|
|
187
|
+
"payload": {
|
|
188
|
+
"title": "Printer is on fire",
|
|
189
|
+
"priority": "high"
|
|
190
|
+
}
|
|
191
|
+
}'
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**Example response**
|
|
195
|
+
|
|
196
|
+
Status: 200
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{
|
|
200
|
+
"isSuccess": true,
|
|
201
|
+
"data": {
|
|
202
|
+
"kind": "save",
|
|
203
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
204
|
+
"data": {
|
|
205
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
206
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
207
|
+
"version": 1,
|
|
208
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
209
|
+
"modifiedAt": null,
|
|
210
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
211
|
+
"modifiedById": null,
|
|
212
|
+
"title": "Printer is on fire",
|
|
213
|
+
"status": "open",
|
|
214
|
+
"priority": "high"
|
|
215
|
+
},
|
|
216
|
+
"changes": {
|
|
217
|
+
"title": "Printer is on fire",
|
|
218
|
+
"status": "open",
|
|
219
|
+
"priority": "high"
|
|
220
|
+
},
|
|
221
|
+
"previous": {},
|
|
222
|
+
"isNew": true,
|
|
223
|
+
"entityName": "ticket"
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### ticket: update
|
|
229
|
+
|
|
230
|
+
**Update ticket**
|
|
231
|
+
|
|
232
|
+
Changes the title or the priority of a ticket.
|
|
233
|
+
|
|
234
|
+
- Required scope: `tickets:write`
|
|
235
|
+
- Endpoint: `POST /api/write`
|
|
236
|
+
|
|
237
|
+
| Field | Type | Required | Description |
|
|
238
|
+
| --- | --- | --- | --- |
|
|
239
|
+
| `id` | string (uuid) | yes | Ticket ID |
|
|
240
|
+
| `version` | number | yes | |
|
|
241
|
+
| `changes` | object | yes | |
|
|
242
|
+
| `changes.title` | string | no | Title |
|
|
243
|
+
| `changes.status` | "open" \| "closed" | no | Status |
|
|
244
|
+
| `changes.priority` | "low" \| "normal" \| "high" | no | Priority |
|
|
245
|
+
|
|
246
|
+
**Example request**
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
curl -X POST https://helpdesk.example.com/api/write \
|
|
250
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
251
|
+
-H "Content-Type: application/json" \
|
|
252
|
+
-d '{
|
|
253
|
+
"type": "helpdesk:write:ticket:update",
|
|
254
|
+
"payload": {
|
|
255
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
256
|
+
"version": 1,
|
|
257
|
+
"changes": {
|
|
258
|
+
"priority": "normal"
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}'
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**Example response**
|
|
265
|
+
|
|
266
|
+
Status: 200
|
|
267
|
+
|
|
268
|
+
```json
|
|
269
|
+
{
|
|
270
|
+
"isSuccess": true,
|
|
271
|
+
"data": {
|
|
272
|
+
"kind": "save",
|
|
273
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
274
|
+
"data": {
|
|
275
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
276
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
277
|
+
"version": 2,
|
|
278
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
279
|
+
"modifiedAt": "2026-01-15T09:30:00.000Z",
|
|
280
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
281
|
+
"modifiedById": "00000000-0000-4000-8000-000000000003",
|
|
282
|
+
"title": "Printer is on fire",
|
|
283
|
+
"status": "open",
|
|
284
|
+
"priority": "normal"
|
|
285
|
+
},
|
|
286
|
+
"changes": {
|
|
287
|
+
"priority": "normal"
|
|
288
|
+
},
|
|
289
|
+
"previous": {
|
|
290
|
+
"id": "00000000-0000-4000-8000-000000000001",
|
|
291
|
+
"tenantId": "00000000-0000-4000-8000-000000000002",
|
|
292
|
+
"version": 1,
|
|
293
|
+
"insertedAt": "2026-01-15T09:30:00.000Z",
|
|
294
|
+
"modifiedAt": null,
|
|
295
|
+
"insertedById": "00000000-0000-4000-8000-000000000003",
|
|
296
|
+
"modifiedById": null,
|
|
297
|
+
"title": "Printer is on fire",
|
|
298
|
+
"status": "open",
|
|
299
|
+
"priority": "high"
|
|
300
|
+
},
|
|
301
|
+
"isNew": false,
|
|
302
|
+
"entityName": "ticket"
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
```
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "API tokens"
|
|
3
|
+
description: "Create an API token for Helpdesk, choose its scopes and send it with your requests."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
An API token lets a script or another service call the Helpdesk API in your name. Its scopes decide which data it may read or change.
|
|
7
|
+
|
|
8
|
+
## Create a token
|
|
9
|
+
|
|
10
|
+
1. Open Settings › API tokens.
|
|
11
|
+
2. Choose **Create a new token**.
|
|
12
|
+
3. Enter a name, pick the scopes and the expiry, and confirm with your password.
|
|
13
|
+
4. Copy the token. It starts with `kpat_` and is shown only once.
|
|
14
|
+
|
|
15
|
+
A token expires after 90 days unless you pick another expiry. The longest possible expiry is 3650 days.
|
|
16
|
+
|
|
17
|
+
## Use the token
|
|
18
|
+
|
|
19
|
+
Send the token in the `Authorization` header. Requests with a token need no cookie and no CSRF token.
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
curl -X POST https://helpdesk.example.com/api/query \
|
|
23
|
+
-H "Authorization: Bearer $API_TOKEN" \
|
|
24
|
+
-H "Content-Type: application/json" \
|
|
25
|
+
-d '{
|
|
26
|
+
"type": "helpdesk:query:ticket:detail",
|
|
27
|
+
"payload": {
|
|
28
|
+
"id": "00000000-0000-4000-8000-000000000001"
|
|
29
|
+
}
|
|
30
|
+
}'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Scopes
|
|
34
|
+
|
|
35
|
+
Each scope comes in two levels. `read` allows the read handlers. `write` allows everything `read` allows plus the write handlers.
|
|
36
|
+
|
|
37
|
+
| Scope | Grant | Handlers |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| `tickets` (Tickets) | `tickets:read` | `helpdesk:query:ticket:detail`, `helpdesk:query:ticket:list` |
|
|
40
|
+
| `tickets` (Tickets) | `tickets:write` | `helpdesk:write:ticket:close`, `helpdesk:write:ticket:create`, `helpdesk:write:ticket:update` |
|
|
41
|
+
|
|
42
|
+
## Rate limit
|
|
43
|
+
|
|
44
|
+
Each token may send 60 requests per 60 seconds. Above that the API answers 429 `pat_rate_limited`.
|
|
45
|
+
|
|
46
|
+
API tokens are included in every Helpdesk plan.
|
|
47
|
+
|
|
48
|
+
## Errors
|
|
49
|
+
|
|
50
|
+
| HTTP status | Code | Cause |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| 401 | `missing_token` | No `Authorization` header. |
|
|
53
|
+
| 401 | `invalid_token` | The token is unknown, revoked or expired. |
|
|
54
|
+
| 403 | `access_denied` | The token lacks the scope for this handler. |
|
|
55
|
+
| 403 | `access_denied` | The endpoint does not accept tokens. Tokens work only on the API endpoints. |
|
|
56
|
+
| 429 | `pat_rate_limited` | Too many requests from this token. |
|
|
57
|
+
|
|
58
|
+
## Revoke a token
|
|
59
|
+
|
|
60
|
+
Revoke a token in Settings › API tokens as soon as you stop using it. Changing your password revokes all your tokens. A token always acts with your current roles. If you leave the account or your user is deleted, it stops working.
|
|
61
|
+
|
|
62
|
+
## Security
|
|
63
|
+
|
|
64
|
+
- Treat a token like a password. Keep it in a secret store, never in code, a repository, an app or web page, or a log.
|
|
65
|
+
- Give each script its own token with only the scopes it needs.
|
|
66
|
+
- Revoke tokens you no longer use. Revoke a token at once if it may have leaked.
|