API usage

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.

  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.

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): 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.
Did not find what you need?

Write to us or book a call. We answer questions about features, installation and licensing.

Contact us