Authentication

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:8080

Sign inCopy Anchor Link

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

The answer is the new session:

{"token": "bpms_...", "expiresAt": "...", "tenant": "tnt_...", "passwordChangeRequired": false}

Send the tokenCopy Anchor Link

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 passwordCopy Anchor Link

Change the password with the current and the new password. The new password must follow the installation's password policy: by default, 8 to 100 characters with a lowercase letter, an uppercase letter, a digit, and a symbol. 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>"}'

A wrong current password answers 401 but does not count as a failed sign-in.

Expired credentialsCopy Anchor Link

A user whose credentials expired in BPMS 3.x can still sign in, and the answer carries passwordChangeRequired: true. Until the password changes, that session can only change the password or sign out: every other call answers 403 with the code core.password-change-required. After the change, the same session works normally.

Sign outCopy Anchor Link

curl -sS -X POST "$BPMS_URL/api/v1/auth/logout" -H "Authorization: Bearer $TOKEN"

After signing out, the token no longer authenticates.

Lockout and attempt limitsCopy Anchor Link

• Lockout. As in BPMS 3.x, a user is locked once the failed sign-ins in a row exceed the limit, 5 by default, so the sixth wrong password locks the user. The attempt that locks the user also closes all of the user's open sessions. A locked user is refused even with the right password until the user is unlocked in BPMS 3.x. A successful sign-in before the limit resets the count.
• Attempt limits. Sign-in attempts are limited per client address and per account, 30 and 10 per minute by default. Over the limit, the call answers 429 and the Retry-After header says how many seconds to wait.
• No hints. Every failed sign-in, whatever the cause, answers the same 401, so the answer never reveals whether a user exists or is locked.

Each deployment can change these values.

SessionsCopy Anchor Link

• A session lasts 9 hours by default; after that, calls answer 401 and the user signs in again.
• A user keeps at most 3 sessions at a time; signing in a fourth time closes the oldest.
• Passwords stored by BPMS 3.x keep working, and each one is upgraded to Argon2id at the user's first successful sign-in.

ErrorsCopy Anchor Link