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 for verifying users when logging into the ABRA Flexi WUI web interface. It is also one of the options for authenticating users of the REST API. All you need to do is send an authentication header with each HTTP request. If you don't provide the header, you will be redirected to the login form, or a status code 401 Authorization required (HTTP authentication required) will be returned.

We try to detect REST API calls and continue offering HTTP authentication. If detection were to fail, 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, which might look like this: "https://jmeno:heslo@adresa_serveru:5434/c/firma/evidence". Our other guide describes how to construct the URL.

Two-factor verification

If two-factor verification is active, HTTP authentication must be supplemented with the otp query parameter 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 the API is described in two-factor verification.

JSON authentication (authentication session)

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

POST /login-logout/login.json

Note: This method only provides results in JSON format, so make sure to correctly specify the required format in the request.

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"
}

Unsuccessful authentication

Unsuccessful 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 requests in three ways:

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

Warning: With the URL query variant, the authentication credentials 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 calling it once every 30 minutes should also 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>

You can also add the returnUrl parameter to 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 a filled-in email address can have a reset token sent to them by email, from a server with SMTP configured, which can be used to change the password.

Sending the email

PUT /password-reset/send-email

The JSON request body 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 specified email address.

Token verification and password change

PUT /password-reset/set-password

The JSON request body contains the following items:


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

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

Authentication