Authentication
Sign in, send the token, change the password, and sign out.
Every call under /api/ needs a session token. You get one by signing in with a BPMS username and password, the same ones the user has in BPMS 3.x, and you send it in the Authorization header of every other call.
The examples use BPMS_URL for the address of your server; the Quick start serves it at http://127.0.0.1:8080:
export BPMS_URL=http://127.0.0.1:8080Sign in
Put the credentials in a login.json file kept out of version control, so the password stays out of your shell history:
{"username": "<username>", "password": "<password>"}curl -sS -X POST "$BPMS_URL/api/v1/auth/login" \
-H 'Content-Type: application/json' -d @login.jsonThe answer is the new session:
{"token": "bpms_...", "expiresAt": "...", "tenant": "tnt_...", "passwordChangeRequired": false}| Field | Meaning |
|---|---|
token | The session token, shown only in this answer. Treat it as a password. |
expiresAt | When the session ends, 9 hours after sign-in by default. |
tenant | The public token of the user's tenant. |
passwordChangeRequired | true when the user must change the password before anything else. |
Send the token
Send the token in the Authorization header of every other call:
TOKEN='<token from the sign-in answer>'
curl -sS -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles"The token also decides the tenant: every call sees only the data of the user's tenant.
Change the password
When passwordChangeRequired is true, every call except changing the password and signing out answers 403. Change it with the current and the new password; a successful change answers 204:
curl -sS -X POST "$BPMS_URL/api/v1/auth/password" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"currentPassword": "<current password>", "newPassword": "<new password>"}'Sign out
curl -sS -X POST "$BPMS_URL/api/v1/auth/logout" -H "Authorization: Bearer $TOKEN"After signing out, the token no longer authenticates.
Errors
| Status | code | When |
|---|---|---|
401 | core.invalid-credentials | The sign-in failed, whatever the cause, or the current password is wrong. |
401 | core.authentication-required | The call has no valid token. |
403 | core.password-change-required | The password must be changed first. |
429 | core.too-many-login-attempts | Too many sign-in attempts; wait the seconds in Retry-After. |
A user is locked after too many failed sign-ins, as in BPMS 3.x, and a locked user is refused even with the right password until the user is unlocked in BPMS 3.x.