Skip to content

Authentication

Four flows share one base URL: the user login, the token refresh, the password recovery and the OAuth token for registered clients.

Check a user

POST /auth/check-user
Field Required Meaning
workspace yes The workspace to look in
username yes The user name 
{"exists": true,
 "user": {"username": "admin", "name": "Administrator admin", "workspace": "starter", "status": "ACTIVE"},
 "auth": {"type": "local", "source": null}}

auth.type says how the user signs in. local means the password of the platform; any other value means an external authentication source, and the login call behaves differently.

Log in

POST /auth/login
Field Required Meaning
workspace yes The workspace
username yes The user name
password yes The password
timezone_offset no The client's offset, used for the dates shown after login
user_lang no A preferred language for the response
remember_me no Keep the session longer 
{"success": true,
 "uid": "…",
 "redirect_url": "/starter/en/lurana/adminPanel/main?page=modern#/home/inbox",
 "tokens": {"access_token": "…", "refresh_token": "…", "token_type": "bearer", "expires_in": 300},
 "user": {"uid": "…", "username": "admin", "fullname": "Administrator admin", "role": "LURANA_ADMIN", "workspace": "starter"}}

The response also carries a timezone block: when mismatch is true, the client's timezone differs from the one stored for the user, and the list of timezones is offered so the client can correct it with auth/update-timezone.

A failed login returns success: false with the reason; it does not return tokens.

Refresh

POST /auth/token/refresh
Field Required
refresh_token yes

It returns a new access and refresh pair. The refresh token expires too, so a client that stays idle for longer than its lifetime must log in again.

Update the timezone

POST /auth/update-timezone
Field Meaning
timezone The IANA name, for example America/La_Paz

Password recovery

Three calls, in this order:

Call Fields Result
POST /auth/forgot-password workspace, username, email, locale Sends the reset message
POST /auth/validate-reset-token token Says whether the token is still valid
POST /auth/reset-password token, password, password_confirmation Sets the new password

The recovery call checks that the user exists and that the email matches, and it needs a configured email server; without one it answers that no server is available.

OAuth token

POST /oauth/token

Standard OAuth2 token endpoint for a registered client: client_credentials, authorization_code or refresh_token. The client credentials come from the OAuth clients screen.

An unsupported grant answers 400 with error: unsupported_grant_type, which is the usual cause of a request that looks right and returns nothing.

Using the token

Authorization: Bearer <access_token>

A missing, malformed or expired token answers 401 with {"success":false,"error":"SESSION_EXPIRED"}.

Inside the browser the application can also send the session cookie instead of the token; that is how its own screens call the API. An external integration should always use the bearer token.