tickets

3.0 KB

1. # Connecting an app to a tickets project (for app workers, e.g. gitoria)
3. Source of truth: `README.md` section "Connecting an app to a project" of tickets.worldapi.org. Base URL: `https://tickets.worldapi.org`.
4. Always send a `user-agent` header (Cloudflare blocks default script agents).
6. ## 1. Send the browser to tickets
7. `GET /connect?app=<name>&label=<owner/repo>&return=<url>&state=<opaque>`
8. - `app` required (≤ 60 chars); `label`, `state` optional (state ≤ 200 chars, comes back unchanged).
9. - `return` = the app's page that receives the answer: https on `worldapi.org` or a subdomain (dev copies: an origin listed in the
10. tickets env `TICKETS_CONNECT_ORIGINS`). Max 500 chars, URL-safe characters only, no `#`. Otherwise `400` with a reason.
11. - Answer: redirect to `/connect/<nonce>`. There the person logs in (ident), picks a project they are ADMIN of (or makes a new one) and confirms.
13. ## 2. The return redirect
14. The browser comes back to `<return>?code=<one-time code>&state=<state>` (`?` becomes `&` if `return` already has a query).
15. The code is valid 5 minutes and works once. The request itself is valid 1 hour.
17. ## 3. Exchange (from the app's SERVER, never the browser)
18. `POST /api/connect/exchange` with `Content-Type: application/json`, body `{"code": "<code>"}`
19. → `200 {"key": "tktc_<48 hex>", "project": "<slug>", "title": "<title>", "api": "https://tickets.worldapi.org/api/projects/<slug>"}`.
20. Wrong / used / expired code → `400 {error}`. GET → 405. The key is shown ONCE; store it like a secret.
21. A second connection of the same app + label to the same project replaces the first (old key dies). An admin can disconnect: key dies at once.
23. ## 4. Using the key
24. Every call: `Authorization: Bearer tktc_…` and, on every write, `X-Tickets-Identity: <ident public id of the person>`.
25. The person must have logged in to tickets once and chosen a display name; the project's roles apply to them. The person is the author.
26. The key reaches ITS project only (other project → 403; no/unknown identity → 403 naming the header) and only these writes (JSON, strict — unknown fields → 400):
28. | what | request | body |
29. |---|---|---|
30. | create ticket | `POST <api>/tickets` | `{"subject": "…", "summary"?: "…", "source"?: "…", "assignee"?: "…"}` |
31. | event: comment | `POST <api>/tickets/<n>/comments` | `{"text": "…"}` (Markdown) |
32. | event: state change | `POST <api>/tickets/<n>/state` | `{"state": "…", "text"?: "…"}` |
34. `<api>` = the `api` value from the exchange (`/api/projects/<slug>`). Create answers `201 {ticket, existed}` (`200` if the same ticket exists).
35. "Mentioned in PR" / "fixed by commit" = a comment, or a state change with a `text`. Any other endpoint with a key → 401.
36. Reads need no key: `GET <api>/tickets`, `GET <api>/tickets/<n>` (add `Accept: text/markdown` for the Markdown view),
37. `GET /api/projects/<slug>/connections` (who is connected).
39. ```bash
40. curl -s -A gitoria -H "Authorization: Bearer $KEY" -H "X-Tickets-Identity: $IDENT_ID" \
41. -H 'content-type: application/json' -d '{"text":"Fixed by commit abc123"}' "$API/tickets/7/comments"
42. ```