﻿# API usage

> 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.

Source: https://workwise-solutions.net/docs/api-usage/ · Language: en · Hungarian version: https://workwise-solutions.net/hu/docs/api-usage/

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](https://workwise-solutions.net/docs/features/personal-access-tokens/) created on **Személyes Hozzáférési Tokenek**. The token acts with the permissions of the user who created it.

1. Create a token and store its **refresh token** securely.
2. Exchange the refresh token for an access token:

   ```bash
   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 `accessToken` and a new `refreshToken` (each with `token` and 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.

3. Send the access token with every call:

   ```bash
   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.

4. When the access token expires (8 hours by default), repeat step 2.

![Personal access tokens](https://workwise-solutions.net/docs/images/diagram-pat-en.png)
*The refresh token is exchanged for a new pair; the access token is sent with every call.*

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.json` ends 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](https://workwise-solutions.net/docs/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](https://workwise-solutions.net/docs/features/service-user-catalog/) or your own vault.
