Authentication Methods

HTTP authentication
JSON authentication
SAMLv2*
OpenID*

* Supported only on local installations. Availability is limited by the ABRA Flexi license. Configured in the server's web interface at /admin/auth-settings.

HTTP Authentication

Basic HTTP authentication is the original method of verifying users when logging into the ABRA Flexi WUI web interface. It is also one of the options for authenticating REST API users. Simply send an authentication header with each HTTP request. If the header is not provided, the request will be redirected to the login form, or status 401 Authorization required will be returned (requesting HTTP authentication).

We try to detect REST API calls and continue offering HTTP authentication. If detection fails, or if you need to control the authentication method, you can use the ?auth=http parameter (see URL parameters).

Example of communication using basic HTTP authentication with the curl command:

curl -L -v -u winstrom:winstrom 'https://demo.flexibee.eu:5434/c/demo/adresar.xml?detail=custom:kod&limit=1'

⋮ * Server auth using Basic with user 'winstrom' > GET /c/demo/adresar.xml?detail=custom:kod&limit=1 HTTP/1.1 > Host: demo.flexibee.eu:5434> Authorization: Basic d2luc3Ryb206d2luc3Ryb20= > User-Agent: curl/7.54.1 > Accept: */* > < HTTP/1.1 200 OK < Cache-Control: private, max-age=0, no-cache < Set-Cookie: lang=cs;Version=1 < Vary: Accept < Content-Type: application/xml < Content-Length: 150 < Via: 1.1.loadbal-fra-1.c.flexibee.eu <      755  AAA

For an example of authentication in PHP, see the real-world examples in the API series.

Basic HTTP authentication can also be sent directly in the URL address, which might look like this: "https://jmeno:heslo@adresa_serveru:5434/c/firma/evidence". Our other guide describes how to build the URL address.

Two-Factor Authentication

If two-factor authentication is active, HTTP authentication must be supplemented with the query parameter otp containing the current one-time password value, for every request:

curl -L -v -u winstrom:winstrom 'https://demo.flexibee.eu:5434/c/demo/adresar.xml?detail=custom:kod&limit=1&otp={otp-code}'

Enabling and disabling verification via API is described in two-factor authentication.

JSON Authentication (Authentication Session)

If you want to authenticate with ABRA Flexi and use the created authentication for further calls, use the API to obtain an authentication token:

POST /login-logout/login.json

Note: The method provides results only in JSON format, so make sure to specify the correct requested format in the query.

The call must include login credentials. The server accepts both raw data (JSON) and form data (application/x-www-form-urlencoded):

`username`	Username
`password`	User password
`otp`	One-time password (if required)

Example call (raw data):

{    "username": "novak",    "password": "heslo"}

Successful Authentication

The result is a success flag success=true and an authentication token authSessionId. The response also includes refreshToken for renewing the session and csrfToken:

{
  "success": true,
  "authSessionId": "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
  "refreshToken": "4f133f49-ba39-4203-a05a-52fe1c3be244:c42cf011-e439-4d9d-b8c4-780579c20c3e",
  "csrfToken": "f30ad42d-e30b-4bf8-91f2-96fdde02cf70"
}

Failed Authentication

Failed authentication is signaled by the success=false flag with a detailed description in the errors string.reason:

{    "success": false,    "errors": {        "reason": "Bylo zad\u00e1no chybn\u00e9 u\u017eivatelsk\u00e9 jm\u00e9no \u010di heslo."    }}

Ways to Use the Authentication Token

The obtained authentication can be passed in queries in three ways:

Cookie: authSessionId: 00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff
HTTP header: X-authSessionId: 00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff
URL query ?authSessionId=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff

Warning: With the URL query variant, authentication data will be logged on the ABRA Flexi server.

To keep the token valid, you need to maintain the connection by occasionally calling GET /login-logout/session-keep-alive.js. We call it every 60 seconds, but once every 30 minutes should be sufficient.

If you want to use the refreshToken, you need to send it as a cookie with the GET /login-logout/check request, which will give you a new authSessionId.

The API can also be used to log out users.

Placing a Login Form on Your Website

If you need to place a login form on your website, use this HTML as inspiration:

<form action="https://demo.flexibee.eu:5434/login-logout/login.html" method="POST"> 
Jméno: <input type="text" name="username" value=""/>
<br/> 
Heslo: <input type="password" name="password"/>
<br/> 
<input type="submit" name="submit" value="Přihlásit"/> 
</form>

It is also possible to add the returnUrl parameter and specify the address to which the user should be redirected. If you use OTP, you also need to add the otp parameter. This method cannot be used with SSO (OpenID or SAMLv2).

Resetting a Forgotten Password

A user with an email address on file can have a reset token sent to their email on a server with SMTP configured, which can be used to change the password.

Sending the Email

PUT /password-reset/send-email

The request body in JSON format contains a single item, email, with the user's email address.

ℹ️ For security reasons, the system will not return an error if no record matches the provided email address.

Verifying the Token and Changing the Password

PUT /password-reset/set-password

The request body in JSON format contains the following items:


`resetToken`	The token the user received by email
`password`	New password. Must meet the minimum password strength requirements.

If you do not include password in the request, only the validity of the token will be checked — success returns 200, an invalid token returns 400.

Authentication