API usage
On this page
Everything the portal does goes through the WorkSmartHub REST API, so integrations can do the same: create tickets from another system, read statuses into a report, synchronise components, and so on.
Swagger#
When Swagger.Enabled is true in appsettings.json (the default), the interactive API documentation is at /swagger of your installation, and the OpenAPI document at /swagger/api/swagger.json. With Swagger disabled, both answer 404. The Status page shows whether it is enabled.
Each endpoint lists the error codes it can return (for example generic.not_authorized, license.error). Generate API clients from the OpenAPI document of the version you run, and regenerate them after every upgrade: new versions add enum values (for example error and audit types) that a client generated from an older version cannot read.
Authentication with a personal access token#
API clients authenticate with a personal access token created on Személyes Hozzáférési Tokenek. The token acts with the permissions of the user who created it.
-
Create a token and store its refresh token securely.
-
Exchange the refresh token for an access token:
curl -s -X POST https://wsh.example.com/api/pats/refresh-token \ -H "Content-Type: application/json" \ -d '{"refreshToken": "<refresh token>"}'The answer contains a new
accessTokenand a newrefreshToken(each withtokenand expiry). Store the new refresh token: the previous one stops working.POST /api/pats/refresh?refreshToken=<refresh token>does the same, but puts the token in the URL; prefer the JSON body, which keeps it out of URLs and access logs. -
Send the access token with every call:
curl -s -X POST https://wsh.example.com/api/workspaces/query \ -H "Authorization: Bearer <access token>" \ -H "Content-Type: application/json" -d '{}'The query parameter
?access_token=<access token>also works, but the header is better. -
When the access token expires (8 hours by default), repeat step 2.
Rules:
- A PAT authenticates API calls only; it never starts a browser session, and it cannot create other PATs.
- An invalidated or deleted PAT is refused within about 1 minute on every server.
- Changing the JWT signing key in
appsettings.jsonends every token.
GET /api/account/test returns the identity and permissions of the caller; use it to check a token.
Endpoints without sign-in#
| Endpoint | Purpose |
|---|---|
GET /health |
Health check |
GET /api/licensing/status |
Licence status |
POST /api/licensing/set |
Upload a licence: the request body is the raw licence file (Content-Type: application/octet-stream, for example curl --data-binary @license.key), not a multipart form. Open only while there is no valid licence; replacing a valid one needs a Super Admin token. |
GET /api/app/mobile-activation |
Mobile app activation (needs the licensed feature) |
Examples#
Most list endpoints are POST .../query with a JSON filter body (an empty {} returns the first page).
| Task | Call |
|---|---|
| List workspaces | POST /api/workspaces/query |
| List the tickets of a workspace | POST /api/workspaces/{workspaceId}/tickets/admin/query |
| Create a ticket | POST /api/workspaces/{workspaceId}/tickets/admin/create |
| Update a ticket | POST /api/tickets/admin/{workTicketId}/update |
| List clients | POST /api/clients/query |
| List components | POST /api/components/query |
| Query audit entries | POST /api/audit/query |
The same permission rules apply as in the portal (Permissions and roles): for example a technician's token sees only the tickets assigned to that user. Ticket and image uploads use a begin / append / finish sequence of calls; see the endpoint descriptions in Swagger.
Good practice#
- Create a dedicated user for each integration, with only the permissions it needs, and create the token for that user (Super Admins can do this from the user's row).
- Use absolute expiry for tokens of short projects, rolling expiry for long-running integrations, and add an expiry warning to a notification channel.
- Keep tokens in a secret store, for example the service user catalog or your own vault.