procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/docs_info/API-DOCUMENTATION/01-authentication.md

@@ -0,0 +1,180 @@
+# Authentication & Authorization
+
+> Audience: an integrator (human or AI) building an application whose backend is the PROCESIO microservices platform.
+> Source of truth: `BE/Web-Api/WebApi/Application/Middleware/*`, `Application/Controllers/AuthenticationProxy/AuthenticationController.cs`, `Domain/Constants/TokenConstants.cs`, `Domain/Enums/Authentication*` , `Domain/Enums/Authorization/*`.
+
+Everything an external client talks to goes through the **Web-Api gateway**. The gateway runs a fixed middleware chain on every request:
+
+```
+HTTP request
+  → LoggingMiddleware          (request/response logging)
+  → SecureInternalRequests     (only for internal/ endpoints — see §6; 404 if headers missing)
+  → DeserializeToken           (detect auth mode, parse JWT claims into internal headers)
+  → Authentication             (validate the token against Authentication-Proxy/Keycloak)
+  → GetUserFromToken           (hydrate the user context)
+  → Authorization              (enforce the per-route permission)
+  → Controller
+```
+
+Identity itself (users, passwords, sessions, OTP, social login) lives in **Keycloak**, fronted by the **Authentication-Proxy** service. Web-Api never stores passwords — it forwards credentials to the proxy and returns the issued tokens.
+
+---
+
+## 1. The three authentication modes
+
+`DeserializeToken` picks the mode automatically from the headers present (`Domain/Enums/AuthenticationTypes.cs → WebApiAuthTypes`):
+
+| Mode | How the gateway detects it | Use it for |
+| --- | --- | --- |
+| **Bearer JWT** (`Token = 0`) | `Authorization: Bearer <jwt>` header **or** an access-token cookie | Interactive apps, server-to-server with a logged-in user |
+| **API key** (`ApiKey = 1`) | Both `key` and `value` headers present | Headless/machine integrations, scripts, webhook producers |
+| **Anonymous** (`Anonymous = 2`) | Neither of the above, and the endpoint is `[AllowAnonymous]` | Login, token refresh, inbound webhook trigger, public forms, custom-URL launches |
+
+If an endpoint requires auth and none is supplied, the gateway returns **`401 Unauthorized`** (cookie clients may instead get a `307` auto-refresh redirect — see §4).
+
+---
+
+## 2. Logging in (Bearer JWT) — `POST api/Authentication`
+
+This is the entry point that mints a token from a username + password.
+
+- **Method/route:** `POST {baseUrl}/api/Authentication`
+- **Auth:** Anonymous
+- **Content-Type:** `application/x-www-form-urlencoded` (note: **form fields, not JSON**)
+- **Body** (`AuthenticateUserDto`):
+
+  | Form field | Type | Required | Notes |
+  | --- | --- | --- | --- |
+  | `username` | string | yes | The PROCESIO account username/email |
+  | `password` | string | yes | |
+  | `code` | string | no | One-time code (OTP/MFA), when the account requires it |
+
+- **Response `200 OK`** (`AuthenticationTokenResponseDto`, JSON; returned in the body **only when the client is not using cookies** — see §4):
+
+  | JSON field | Type | Meaning |
+  | --- | --- | --- |
+  | `access_token` | string (JWT) | Send as `Authorization: Bearer <access_token>` on later calls |
+  | `expires_in` | number (seconds) | Access-token lifetime |
+  | `refresh_token` | string (JWT) | Used to obtain a new access token |
+  | `refresh_expires_in` | number (seconds) | Refresh-token lifetime |
+  | `token_type` | string | Usually `Bearer` |
+  | `session_state` | string | Keycloak session id |
+  | `scope` | string | Granted scopes |
+  | `error` | string | Present on failure (e.g. `invalid_grant`) |
+  | `error_description` | string | Human-readable failure reason |
+
+**Example**
+
+```bash
+curl -X POST "https://api.procesio.app/api/Authentication" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode "username=alice@example.com" \
+  --data-urlencode "password=•••••••••"
+# → { "access_token": "eyJ...", "expires_in": 300, "refresh_token": "eyJ...", ... }
+```
+
+Then call any protected endpoint:
+
+```bash
+curl "https://api.procesio.app/api/Projects" \
+  -H "Authorization: Bearer eyJ..." \
+  -H "x-version: 1.19"
+```
+
+### Single sign-on (SSO)
+For social / external IdP login the proxy exposes a redirect-based OAuth2 flow (all Anonymous, mostly hidden from Swagger):
+- `GET api/Authentication/authorize/{identityProvider}?redirect_uri=...` → returns the IdP authorization URL.
+- `GET api/Authentication/oauth2/callback/{identityProvider}` → IdP redirects here; PROCESIO completes login and issues tokens.
+- `GET api/Authentication/otp/callback` → OTP completion.
+
+`identityProvider` is the `IdentityProvider` enum (see `03-auth-users-workspaces.md`).
+
+---
+
+## 3. Refreshing & ending a session
+
+| Action | Endpoint | Body (`x-www-form-urlencoded`) |
+| --- | --- | --- |
+| Refresh access token | `POST api/Authentication/refreshToken` | `refresh_token` (required), `client_id` (default `procesio-ui`) |
+| Log out current session | `POST api/Authentication/logOut` | `refresh_token` |
+| Log out **all** sessions | `DELETE api/Authentication/logOut` | `token` (an access token) |
+
+All three are Anonymous (they authenticate by possession of the refresh/access token itself).
+
+---
+
+## 4. Two client styles: token-in-body vs. cookie (BFF)
+
+The same auth endpoints serve two client styles, decided by whether the request carries the PROCESIO UI cookie marker:
+
+- **Programmatic clients (recommended for integrations):** do **not** use cookies. `POST api/Authentication` returns the full `AuthenticationTokenResponseDto` in the body. You store `access_token` and send it as `Authorization: Bearer ...`. You refresh manually via `refreshToken`.
+- **Browser/BFF clients (the PROCESIO SPA):** the gateway sets HTTP-only cookies `__Host-procesio.access` / `__Host-procesio.refresh` (`__Dev-` prefix in debug builds) and returns only `{ "message": "Authentication successful" }`. When the access token expires, the gateway transparently refreshes from the cookie and replies `307 Temporary Redirect` to the same path so the browser retries with fresh cookies. A `x-session-expires-at` response header carries the refresh-token expiry.
+
+> For an app builder, prefer the **token-in-body** style — it is stateless and predictable. Only the official SPA needs the cookie path.
+
+---
+
+## 5. API keys (headless auth) — alternative to JWT
+
+API keys let a machine integration authenticate without a user login. They are **workspace-scoped** and managed under `api/ApiKey` (see `12-webhooks-notifications-misc.md`).
+
+- **Create:** `POST api/ApiKey` (JWT-authenticated) returns the secret **once**. A user may hold up to **25** keys.
+- **Use:** send two headers on every request:
+
+  | Header | Value |
+  | --- | --- |
+  | `key` | the 16-char key **name** |
+  | `value` | the 64-char key **secret** |
+
+  Optionally set `auth_type: 1` to force API-key mode. The gateway looks the key up within its workspace, checks it is active, and validates the secret against a stored hash.
+
+```bash
+curl "https://api.procesio.app/api/Projects" \
+  -H "key: myintegrationkey" \
+  -H "value: <64-char-secret>" \
+  -H "x-version: 1.19"
+```
+
+> **Restriction:** API-key requests are explicitly **rejected by every `api/ApiKey` management endpoint** — you must use a JWT to create/list/delete keys. API keys are for calling the *rest* of the API.
+
+---
+
+## 6. Authorization model — permissions per endpoint
+
+Once authenticated, the `Authorization` middleware enforces a permission derived from two attributes on the controller/action:
+
+- **Entity** — `[AuthorizationEntity(AuthorizationEntityType.X)]` (controller level). Values (`Domain/Enums/Authorization/AuthorizationEntityType.cs`):
+
+  `MasterWorkspace(1)`, `Workspace(2)`, `ProcessDesigner(3)`, `ProcessInstance(4)`, `CustomActions(5)`, `DataModels(6)`, `Credentials(7)`, `DocumentDesigner(8)`, `Webhook(9)`, `Schedule(10)`, `ApiKey(11)`, `FormTemplate(12)`, `FormInstance(13)`, `DataStore(14)`, `ProcesioAdmin(101)`, `None(102)`.
+
+- **Action** — `[AuthorizationAction(AuthorizationActionType.X)]` (method level). Values (`AuthorizationActionType.cs`):
+
+  `None(1)` = authenticated but no specific permission required · `Read(2)` · `Update(3)` · `Create(4)` · `Delete(5)` · `Admin(6)`.
+
+The effective permission documented per endpoint is written **`Entity:Action`** (e.g. `ProcessInstance:Read`, `Credentials:Create`). `Permission: None` means "any authenticated caller". `ProcesioAdmin:*` endpoints require platform-admin rights and are typically hidden from Swagger (but still reachable).
+
+> **Internal endpoints are out of scope for external clients.** Routes beginning with `internal/` (and controllers marked `[SecureInternalController]`) require the `prc-service` + `prc-code` headers and return **404** to anyone else. They are service-to-service only and are *not* documented in the endpoint reference. See [Appendix: internal & inter-service surface](endpoints/99-internal-and-other-services.md).
+
+---
+
+## 7. Workspace context
+
+PROCESIO is multi-tenant via **workspaces**. A user belongs to one or more workspaces under a **master workspace**. Most data operations are scoped to the "active" workspace:
+
+- The active workspace is normally encoded in the JWT, but many endpoints accept an explicit override:
+  - Header `workspaceId: <guid>`, or
+  - Query param `targetWorkspace=<guid>` (declared via the `[HasOptionalParameter]` filter on endpoints that support switching).
+- Master-workspace-level operations use the `MasterWorkspace` entity; per-workspace operations use `Workspace`.
+
+When building an app that spans multiple workspaces, pass the target workspace explicitly on each call rather than relying on a default.
+
+---
+
+## 8. Quick-start checklist for an integration
+
+1. **Get a token:** `POST /api/Authentication` (form-urlencoded) → keep `access_token` + `refresh_token`. *(Or create an API key in the UI and use `key`/`value` headers.)*
+2. **Always send** `Authorization: Bearer <token>` (or `key`+`value`) and `x-version: 1.19`.
+3. **Pick the workspace** with `workspaceId`/`targetWorkspace` when needed.
+4. **Refresh** before `expires_in` elapses via `POST /api/Authentication/refreshToken`.
+5. **Call the domain endpoints** documented in [`endpoints/`](endpoints/). The most common goal — *run an automation* — is in [`04-processes.md`](endpoints/04-processes.md).
+6. **For realtime results** (async action/test/CSV runs) open the SignalR hub — see [`13-realtime-signalr.md`](endpoints/13-realtime-signalr.md).

procesio_cli/tools/procesio/docs_info/API-DOCUMENTATION/02-conventions.md

@@ -0,0 +1,116 @@
+# API conventions
+
+> Shared rules that apply to every Web-Api endpoint in this reference. Read this once; the per-domain files assume it.
+
+---
+
+## 1. Base URL
+
+All paths in this reference are **relative to the Web-Api gateway host** of your PROCESIO deployment:
+
+| Deployment | Example gateway base URL |
+| --- | --- |
+| PROCESIO public cloud (historical SaaS) | `https://api.procesio.app` |
+| On-prem / self-hosted | your install's gateway host (e.g. `https://procesio.your-company.internal`) |
+| Local dev | `http://localhost:<port>` (the container binds Kestrel on port `8000`) |
+
+A full request URL is therefore `{baseUrl}` + the route shown, e.g. `https://api.procesio.app/api/Projects`.
+
+> The FE origins allowed by CORS in the reference config are `https://procesio.app`, `https://dev.procesio.app`, `https://qa.procesio.app`, `https://forms.procesio.app` (+ a few customer hosts). Server-to-server clients are not subject to CORS.
+
+There is **no version segment in the path** — see §3.
+
+---
+
+## 2. Standard headers
+
+| Header | Direction | When | Notes |
+| --- | --- | --- | --- |
+| `Authorization: Bearer <jwt>` | request | JWT auth | See [authentication](01-authentication.md) |
+| `key` + `value` | request | API-key auth | Alternative to `Authorization` |
+| `x-version` | request | optional | API version selector; defaults to `1.19` |
+| `Content-Type` | request | bodies | `application/json` unless an endpoint says `x-www-form-urlencoded` or `multipart/form-data` |
+| `workspaceId` / `?targetWorkspace=` | request | optional | Select the active workspace |
+| `x-session-expires-at` | response | cookie clients | Refresh-token expiry (epoch) |
+| `x-requested-by: playground-v1` | request | SPA only | Marks the official UI/BFF cookie flow |
+
+---
+
+## 3. API versioning
+
+- Versioning uses the **`x-version` request header** (`HeaderApiVersionReader("x-version")`), **not** a URL segment or query string.
+- Current/default version is **`1.19`** (`WebApiConstants.CURRENT_API_VERSION`). If the header is omitted the gateway assumes the default (`AssumeDefaultVersionWhenUnspecified = true`).
+- The server reports supported versions back via the `api-supported-versions` response header (`ReportApiVersions = true`).
+- **Recommendation:** always send `x-version: 1.19` so your client is pinned to a known contract.
+
+---
+
+## 4. Content types & serialization
+
+- Request/response bodies are **JSON** serialized with **Newtonsoft.Json** unless stated otherwise.
+- A handful of endpoints use other content types:
+  - `application/x-www-form-urlencoded` — the auth endpoints (`api/Authentication/*`).
+  - `multipart/form-data` — file/package uploads (file controllers, custom-action & platform-action upload, credential certificate upload, CSV import). The file part name is usually **`package`** (`file` for CSV import); other inputs ride as **request headers**, not form fields. See the relevant domain doc.
+  - Binary streams — file/document **downloads** return raw bytes with the stored MIME type and a download filename (not JSON), despite the class-level `[Produces("application/json")]`.
+- **Wire field names:** JSON property names follow the C# property unless overridden by `[JsonProperty("...")]` or, for form fields, `[ModelBinder(Name="...")]` / `[FromForm(Name=...)]`. The per-domain docs list the **wire name** for every field.
+
+### C# → JSON type mapping used throughout
+
+| C# type | Wire type |
+| --- | --- |
+| `Guid` | `string` (uuid) |
+| `DateTime` / `DateTimeOffset` | `string` (ISO-8601 date-time) |
+| `bool` | `boolean` |
+| `int` / `long` / `decimal` / `double` | `number` |
+| `string` | `string` |
+| `enum` | `number` (the underlying int) — or its name; enums are listed with values per field |
+| `List<T>` / `T[]` | `array` of `T` |
+| nested class | `object` (defined in that file's **Shared DTOs** section) |
+| `object` / `JToken` | free-form JSON (shape not constrained server-side) |
+
+---
+
+## 5. Error responses
+
+Most validation/domain errors return an **array of `ApiErrorResponse`** (`Infrastructure.Core.CustomError.ApiErrorResponse`):
+
+```json
+[
+  { "statusCode": 1001, "value": "Entity not found.", "target": "id" }
+]
+```
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `statusCode` | number | A PROCESIO **`ErrorCodes`** enum value (a domain error code) — **not** the HTTP status |
+| `value` | string\|object | Human-readable message (resolved from the error-code map) |
+| `target` | string\|object | The offending field/property name, when applicable |
+
+Notes:
+- The **HTTP status** conveys the category: `400` validation/bad request, `401` unauthenticated, `403` forbidden (insufficient permission), `404` not found *(also returned intentionally for unauthorized `internal/` calls)*, `409` conflict (e.g. CSV job not finished), `413` payload too large (uploads), `415` unsupported media type (webhook/custom-URL body), `500` server error.
+- A few endpoints return a **bare exception-message string** instead of the array on unhandled errors — clients should tolerate both shapes on `400`/`500`.
+- Anonymous endpoints (forms, custom-URL launch) deliberately apply a small randomized delay (`TimeDelay.RandomWait`) as a timing-attack mitigation.
+
+---
+
+## 6. Pagination, filtering, sorting
+
+There is no single global paging envelope; patterns vary by domain:
+- **Common `Pagination` DTO** (subscriptions/resources): `PageNumber` (only applied when > 1), `PageItemCount` (only applied when > 0). See `11-subscriptions-resources-analytics.md`.
+- **Data Store rows** use **query-string** filters, not a JSON body: `filters[N].displayName`, `filters[N].operator` (numeric `DataStoreRowsFilterOperator`), `filters[N].value`, plus `sort.displayName` + `sort.direction` (1=Asc, 2=Desc). See `09-datastore-datatypes.md`.
+- Many list endpoints expose `searchName`, `count` sibling endpoints, and entity-specific filters — documented inline.
+
+---
+
+## 7. Async operations & realtime
+
+Several operations are **asynchronous**: the HTTP call starts the work and the result is delivered later.
+- **Process launch** can be synchronous (`runSynchronous=true`, blocks up to `secondsTimeOut`) or async (returns `{ "instanceId": "<guid>" }`; poll `GET api/Projects/instances/{id}/status`). See `04-processes.md`.
+- **Connector/test-action runs and CSV import/export** push their results over **SignalR**. Obtain a `connectionId` from the hub and pass it (body `ConnectionId` or header `connectionId`) to the start endpoint. See `13-realtime-signalr.md`.
+
+---
+
+## 8. Health
+
+- `GET /health` — liveness/readiness (anonymous, bypasses the auth chain). Not part of the business API.
+- Prometheus metrics are exposed on a separate port (`9090`, `/metrics`) and are not reachable through the public API path.

procesio_cli/tools/procesio/docs_info/API-DOCUMENTATION/ANONYMOUS-SURFACE.md

@@ -0,0 +1,51 @@
+# PROCESIO — the ANONYMOUS surface, enumerated
+
+**Generated** from `API-DOCUMENTATION/endpoints/*.md`. **Do not hand-edit** — regenerate.
+
+> ⚠ **WHY THIS EXISTS.** Three anonymous endpoints were met one incident at a time: `api/Webhooks/launch/{id}` (a bearer id that travels in packs), `api/FormProcess/.../launch`, and `api/Form/dataStore/{id}/rows` (full CRUD, including DELETE, on any store the path names). **All three were documented and none was read before it mattered.**
+
+> ⚠ **THE GENERAL FORM: on every endpoint below the access control is AN ID.** An id is a bearer credential — it travels in process definitions, in exported packs, in shared links, in logs and in browser history. **Treat every `{id}` in this table as a secret, or decide deliberately that it is not.**
+
+| verbs | route | operation | the id that IS the control | documented at |
+|---|---|---|---|---|
+| `POST` | `api/Authentication` | `Authenticate` | `{(none in route)}` | `03-auth-users-workspaces.md:32` |
+| `GET` | `api/Authentication` | `AuthenticationForm` | `{(none in route)}` | `03-auth-users-workspaces.md:45` |
+| `GET` | `api/Authentication/oauth2/callback/{identityProvider}` | `AuthenticateByBroker` | `{identityProvider}` | `03-auth-users-workspaces.md:54` |
+| `GET` | `api/Authentication/otp/callback` | `AuthenticateOTPCallback` | `{(none in route)}` | `03-auth-users-workspaces.md:65` |
+| `GET` | `api/Authentication/authorize/{identityProvider}` | `GetAuthorization` | `{identityProvider}` | `03-auth-users-workspaces.md:74` |
+| `POST` | `api/Authentication/refreshToken` | `RefreshToken` | `{(none in route)}` | `03-auth-users-workspaces.md:84` |
+| `POST` | `api/Authentication/logOut` | `Logout` | `{(none in route)}` | `03-auth-users-workspaces.md:96` |
+| `DELETE` | `api/Authentication/logOut` | `DeleteAllSessions` | `{(none in route)}` | `03-auth-users-workspaces.md:105` |
+| `POST` | `api/Users/otp/setup` | `OtpSetup` | `{(none in route)}` | `03-auth-users-workspaces.md:128` |
+| `POST` | `api/Users` | `CreateUser` | `{(none in route)}` | `03-auth-users-workspaces.md:136` |
+| `PUT` | `api/Users/details` | `UpdateUserDetails` | `{(none in route)}` | `03-auth-users-workspaces.md:145` |
+| `POST` | `api/Users/withActivation` | `CreateUserWithActivationResponse` | `{(none in route)}` | `03-auth-users-workspaces.md:154` |
+| `POST` | `api/Users/resendToken` | `RefreshCreateUserToken` | `{(none in route)}` | `03-auth-users-workspaces.md:164` |
+| `POST` | `api/Users/password/change` | `ChangePassword` | `{(none in route)}` | `03-auth-users-workspaces.md:172` |
+| `POST` | `api/Users/password/forgot` | `ForgotPassword` | `{(none in route)}` | `03-auth-users-workspaces.md:181` |
+| `POST` | `api/Users/password/update` | `UpdatePassword` | `{(none in route)}` | `03-auth-users-workspaces.md:190` |
+| `POST` | `api/Form` | `SaveForm` | `{(none in route)}` | `07-forms-documents.md:65` |
+| `POST` | `api/FormTemplate/{id}/duplicate` | `DuplicateForm` | `{id}` | `07-forms-documents.md:183` |
+| `GET` | `api/FormTemplate/{workspaceId}/{id}` | `GetAnonymousForm` | `{workspaceId}` · `{id}` | `07-forms-documents.md:192` |
+| `GET` | `api/FormProcess/{formTemplateId}/{processTemplateId}` | `GetProcessTemplate` | `{formTemplateId}` · `{processTemplateId}` | `07-forms-documents.md:350` |
+| `POST` | `api/FormProcess/{formTemplateId}/{processTemplateId}/publish` | `PublishFlow` | `{formTemplateId}` · `{processTemplateId}` | `07-forms-documents.md:361` |
+| `POST` | `api/FormProcess/{formTemplateId}/{processTemplateId}/launch` | `LaunchFlowInstance` | `{formTemplateId}` · `{processTemplateId}` | `07-forms-documents.md:375` |
+| `GET` | `api/FormProcess/{formTemplateId}/{processTemplateId}/{processInstanceId}/variables` | `GetFlowInstanceVariables` | `{formTemplateId}` · `{processTemplateId}` · `{processInstanceId}` | `07-forms-documents.md:392` |
+| `POST` | `api/Form/upload` | `UploadFormFile` | `{(none in route)}` | `07-forms-documents.md:412` |
+| `POST` | `api/FormProcess/{formTemplateId}/{flowInstanceId}/upload` | `Upload` | `{formTemplateId}` · `{flowInstanceId}` | `07-forms-documents.md:443` |
+| `GET` | `api/FormProcess/download` | `Download` | `{(none in route)}` | `07-forms-documents.md:461` |
+| `GET` | `api/Form/dataStore/{dataStoreId}/rows` | `GetRows` | `{dataStoreId}` | `07-forms-documents.md:484` |
+| `POST` | `api/Form/dataStore/{dataStoreId}/rows` | `AddRows` | `{dataStoreId}` | `07-forms-documents.md:499` |
+| `PUT` | `api/Form/dataStore/{dataStoreId}/rows` | `UpdateRow` | `{dataStoreId}` | `07-forms-documents.md:509` |
+| `DELETE` | `api/Form/dataStore/{dataStoreId}/rows` | `DeleteRows` | `{dataStoreId}` | `07-forms-documents.md:519` |
+| `GET` | `api/DataTypes/primary` | `GetPrimaryTypes` | `{(none in route)}` | `09-datastore-datatypes.md:478` |
+| `GET` | `api/DataTypes/procesio` | `GetProcesioTypes` | `{(none in route)}` | `09-datastore-datatypes.md:490` |
+| `GET` | `api/DataTypes/primary/count` | `CountPrimaryDataTypes` | `{(none in route)}` | `09-datastore-datatypes.md:502` |
+| `GET|POST|PUT|PATCH|DELETE` | `/{masterWorkspaceUrl}/{workspaceUrl}/{entityUrl}` | `Launch` | `{masterWorkspaceUrl}` · `{workspaceUrl}` · `{entityUrl}` | `10-custom-urls.md:218` |
+| `GET|POST|PUT|PATCH|DELETE` | `/{tinyUrl}` | `Launch` | `{tinyUrl}` | `10-custom-urls.md:248` |
+| `GET|POST|PUT|PATCH|DELETE` | `api/Webhooks/launch/{id}` | `LaunchWebhook` | `{id}` | `12-webhooks-notifications-misc.md:155` |
+| `POST` | `api/Webhooks/launch/{id}/verifone` | `LaunchFormData` | `{id}` | `12-webhooks-notifications-misc.md:193` |
+| `GET` | `api/Webhooks/launch/{id}/verifone` | `LaunchGetFormData` | `{id}` | `12-webhooks-notifications-misc.md:208` |
+
+**Total anonymous endpoints: 38**
+

procesio_cli/tools/procesio/docs_info/API-DOCUMENTATION/README.md

@@ -0,0 +1,104 @@
+# PROCESIO Public API Reference
+
+This is an exhaustive reference of the **public HTTP API** exposed by the PROCESIO low-code automation platform, plus its realtime (SignalR) channel. It is written so that **another AI can generate applications that use PROCESIO as their backend**, without reading the microservice source.
+
+- **Scope:** every public, externally-reachable endpoint of the **Web-Api gateway** (297 REST endpoints across 12 domains) + the System-Notifications SignalR hub. Internal/inter-service endpoints are listed separately and are explicitly out of scope.
+- **Source:** extracted from the PROCESIO Back-End microservice repositories (see [`provenance`](#provenance)). No source was modified.
+- **Language/format:** English, Markdown.
+
+> **What is PROCESIO?** A platform where users design *processes* (automation flows) out of *actions*, optionally fed by *forms*, *files*, *data-store tables*, *credentials*, and triggered manually, on a *schedule*, or via *webhooks*. The public API lets your app do everything the PROCESIO UI can: authenticate, manage these resources, **launch processes and read their results**, and receive realtime events.
+
+---
+
+## Start here
+
+1. **[01 — Authentication & Authorization](01-authentication.md)** — how to get a token (or API key), the permission model, workspaces. **Read this first.**
+2. **[02 — Conventions](02-conventions.md)** — base URL, headers, `x-version`, error format, type mapping, pagination, async/realtime. **Read this second.**
+3. Then jump to the domain you need (table below). To *run an automation* — the most common goal — go straight to **[04 — Processes](endpoints/04-processes.md)**.
+
+---
+
+## Endpoint reference (by domain)
+
+| # | Document | Endpoints | What it covers |
+| --- | --- | --- | --- |
+| 03 | [Auth, Users, Workspaces, Permissions](endpoints/03-auth-users-workspaces.md) | 52 | Login/SSO/OTP, sign-up, self-service account, user CRUD, workspaces & master workspaces, permissions, preferences |
+| 04 | [Processes & Schedules](endpoints/04-processes.md) | 39 | Process templates (designer), **launching & running instances**, instance status/output, debugger, schedules |
+| 05 | [Actions](endpoints/05-actions.md) | 21 | Action prototypes/templates/nodes, connector actions, custom-action upload, platform actions, test runs |
+| 06 | [Files](endpoints/06-files.md) | 8 | Upload/download of files for flows, connector actions, schedules, test actions (multipart + binary stream) |
+| 07 | [Forms & Documents](endpoints/07-forms-documents.md) | 49 | Form templates/instances/applications/chains, **anonymous public form submission & flow launch**, document templates |
+| 08 | [Credentials](endpoints/08-credentials.md) | 21 | Credential vault CRUD, templates, OAuth2 authorization flow, certificate upload |
+| 09 | [Data Store & Data Types](endpoints/09-datastore-datatypes.md) | 38 | Dynamic tables (schema + **rows query/CRUD**), CSV import/export jobs, platform data-type definitions |
+| 10 | [Custom URLs & public launch URLs](endpoints/10-custom-urls.md) | 19 | Vanity/short URLs mapping to forms, webhooks, workspaces; **anonymous catch-all launch routes** |
+| 11 | [Subscriptions, Resources & Analytics](endpoints/11-subscriptions-resources-analytics.md) | 26 | Billing/subscriptions, quota config, process & execution-environment analytics |
+| 12 | [Webhooks, Notifications, API Keys, Transport](endpoints/12-webhooks-notifications-misc.md) | 24 | Webhook CRUD, **anonymous inbound webhook trigger**, notification inbox, **API-key management**, import/export |
+| 13 | [Realtime (SignalR hub)](endpoints/13-realtime-signalr.md) | hub | WebSocket connection, `connectionId` model, server→client events for async results |
+| 99 | [Internal & other services (appendix)](endpoints/99-internal-and-other-services.md) | — | What is **not** public, and why |
+
+**Total public REST endpoints documented: 297** (+ the SignalR hub).
+
+Each domain file lists, per endpoint: HTTP method + full route, auth mode + required permission, path/query params, special headers, request body DTO (every field with wire name, type, required/optional), responses, and notes. Nested/shared DTOs are defined once per file in a "Shared DTOs" section.
+
+---
+
+## Common recipes
+
+> Replace `{baseUrl}` with your deployment's gateway host (e.g. `https://api.procesio.app`). Send `x-version: 1.19` on every call.
+
+### A. Authenticate
+```bash
+curl -X POST "{baseUrl}/api/Authentication" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode "username=USER" --data-urlencode "password=PASS"
+# → access_token, refresh_token, expires_in
+```
+
+### B. Run a process and get the result (one-shot, synchronous)
+```bash
+# id = the process TEMPLATE id; body = the flow's input variables
+curl -X POST "{baseUrl}/api/Projects/{templateId}/run?runSynchronous=true&secondsTimeOut=60" \
+  -H "Authorization: Bearer <token>" -H "x-version: 1.19" \
+  -H "Content-Type: application/json" \
+  -d '{ "payload": { /* input variables */ }, "connectionId": null }'
+```
+Async variant: omit `runSynchronous` → response is `{ "instanceId": "<guid>" }`, then poll:
+```bash
+curl "{baseUrl}/api/Projects/instances/{instanceId}/status?flowTemplateId={templateId}" \
+  -H "Authorization: Bearer <token>" -H "x-version: 1.19"
+```
+The two-step path (`publish` → `launch`) and the full input-variable shape are in [04 — Processes](endpoints/04-processes.md).
+
+### C. Trigger a process from an external system (no auth)
+```bash
+# id = the webhook id configured in PROCESIO; body becomes the trigger payload
+curl -X POST "{baseUrl}/api/Webhooks/launch/{webhookId}" \
+  -H "Content-Type: application/json" -d '{ "any": "payload" }'
+```
+Add `?respondOk=true` for a bare 200, or `?payload=<json>` to override the body. See [12](endpoints/12-webhooks-notifications-misc.md).
+
+### D. Read/write Data Store rows
+- Query: `GET {baseUrl}/api/DataStore/{dataStoreId}/rows?filters[0].displayName=Email&filters[0].operator=1&filters[0].value=a@example.com`
+- Insert/update/delete rows are JSON dictionaries keyed by **column display name**. See [09](endpoints/09-datastore-datatypes.md).
+
+### E. Receive async results in realtime
+Connect to the SignalR hub at `{notificationsHost}/hub/notification?userId=<guid>`, invoke `GetConnectionId()`, pass that `connectionId` to connector/test/CSV start endpoints, and handle the server→client events. See [13](endpoints/13-realtime-signalr.md).
+
+---
+
+## Conventions recap (see [02](02-conventions.md) for detail)
+
+- **Auth:** `Authorization: Bearer <jwt>` *or* `key` + `value` headers (API key). Some endpoints are `[AllowAnonymous]` (login, webhook trigger, public forms, custom-URL launch).
+- **Version:** `x-version` header, default `1.19`. No version in the URL path.
+- **Bodies:** JSON (Newtonsoft) unless noted; auth endpoints use `x-www-form-urlencoded`; uploads use `multipart/form-data` (file part usually named `package`).
+- **Workspace:** select with `workspaceId` header or `?targetWorkspace=<guid>`.
+- **Errors:** array of `{ statusCode (PROCESIO error code), value (message), target (field) }`; HTTP status carries the category.
+
+---
+
+## Provenance
+
+Generated from the PROCESIO Back-End workspace. Repositories were synced on their default branches before extraction:
+
+The public surface is the **Web-Api** gateway (`api/*` routes, port 8000). The SignalR hub is hosted by **System-Notifications** (`/hub/notification`). Extraction date: 2026-06-24. API version at extraction: **1.19**.
+
+> If PROCESIO's source changes, re-sync the repos (`/be-pull`) and re-run the extraction; the `x-version` value and endpoint set may shift.