API concepts¶
The workspace API lets a program read and act on cases without going through the interface. It is the API the application itself uses, documented here for integrations.
Not the legacy interface
This is the current API, served by the application under
/{workspace}/{language}/lurana/api. The older token API under /api/1.0/ is a
different interface and is not covered here.
Base URL¶
{host}/{workspace}/{language}/lurana/api
For example, on a workspace called starter, in English:
https://bpm.example.com/starter/en/lurana/api
The workspace is also sent in the body of most calls. The two must agree: a call to the
starter path that names another workspace in its body is refused.
Requests¶
- The body is JSON: send
Content-Type: application/json. - Almost every route is
POST, including the reads. The exceptions arehome/user-name-formatand the two download routes, which also acceptGET. - Parameters are flat keys in the body, not a nested object.
curl -X POST "$BASE/auth/check-user" \
-H 'Content-Type: application/json' \
-d '{"workspace":"starter","username":"admin"}'
Authentication¶
POST /auth/check-userconfirms the user exists in the workspace.POST /auth/loginreturns an access token and a refresh token.- Send the access token on every other call:
Authorization: Bearer <token>. - When the access token expires,
POST /auth/token/refreshissues a new pair.
The access token is short lived — five minutes — and the refresh token ten. An integration that runs for long has to refresh instead of logging in again.
Without a valid token the API answers:
{"success": false, "error": "SESSION_EXPIRED", "message": "Unauthorized or session expired"}
with HTTP 401.
For a server-to-server integration, POST /oauth/token issues an OAuth2 token
(client_credentials, authorization_code or refresh_token) for a registered
client.
Responses¶
Success responses carry a success flag and their payload:
{"success": true, "data": [ … ]}
Some endpoints return a bare object instead — admin/me, for example, returns user,
workspace, role, groups and permissions at the top level.
Errors keep the same shape:
| HTTP | Body | Meaning |
|---|---|---|
| 401 | {"success":false,"error":"SESSION_EXPIRED",…} |
Missing or expired token |
| 422 | {"success":false,"error":"REQUIRED_FIELDS",…} |
A required parameter is missing |
| 500 | {"success":false,"error":"…"} |
The operation failed |
There is no paging envelope shared by every list: each list endpoint documents its own
parameters and returns its rows in data.
What is documented here¶
| Page | Covers |
|---|---|
| Authentication | Login, refresh, password recovery, OAuth token |
| Cases | Starting, reading and acting on a case: documents, notes, messages, derivation |
| Search and favorites | Global search, favorites, current user |
| Endpoint reference | The 53 integration endpoints, generated from the route files |
What is in scope¶
The API has 169 routes. The ones the admin screens use to call themselves — settings, themes, authentication sources, the email log, OAuth client administration — are not for integrations and are not documented here. What remains is the surface a third party needs:
- sign a user in and renew the token;
- start a case and follow it: read it, upload and download documents, add notes, resend messages, pause, cancel, reassign, derive;
- search the workspace;
- resolve who the token belongs to;
- list the processes a user can start;
- create and update users, with the lists needed to fill a user form.
If an operation is not in that list, it belongs to the administration screens rather than to an integration.