DE EN EN (Google)


Easydb session management

In order to work with the Easydb, the first requirement is to have a session. For most calls, the session has to be authenticated. The authenticated user may be requested to confirm some messages before having full access to the API.

These are the states of a client from the point of view of Easydb:

1. No session

A client without session can only call this method:

This method is in fact always allowed. A client may use different sessions. Other calls require the provided token to identify the session.

Trying to call another method without a token will result in a Not Authenticated error.

2. Unauthenticated session

If the client’s session is not authenticated, little interaction with the server is allowed:

Trying to call another method with an unauthenticated token will result in a Not Authenticated error.

After authenticating, the server checks whether the associated user has pending tasks. Depending on this information, the client will be in state (3) or (4).

3. User with pending tasks

If the user has pending tasks, they can be confirmed using:

The methods from state (2) are allowed as well.

Trying to call another method will result in a Tasks Not Confirmed error.

4. User ready

In this state, all API methods are allowed, provided the user has the required rights. See the “Permissions” section in each call and the general description about rights management.


Standard login (“easydb”)

Users can login using either their login or an email address:

In order to login, the user needs a password. If there is no active password yet or if the administrator specifically required the user to change the password (require_password_change flag), an e-mail will be sent to the user with a link containing the required information to perform a POST /api/session/set_password API call.

The administrator can also set directly a password for a user: this password can be provided directly or generated by the server (_password attribute). Depending on the e-mail setting send_email_include_password, the password will be directly mailed to the user, or an e-mail will be sent, so that the user calls the administrator.

The authentication is performed using POST /api/session/authenticate?method=easydb.

If the user forgets the password, [POST /api/session/forgot_password] can be used to reset it. This only works if the administrator has allowed it in the Base Configuration (system.login.forgotten_password_process). An e-mail is sent to the user with a link containing the required information to call POST /api/session/authenticate?method=task.

Single Sign-On (“sso”)

Anonymous access (“anonymous”)

Shared collection access (“email” and “collection”)

E-mail management

Users have a list of e-mail addresses. An address can be active or inactive. One of the active addresses can be chosen as “primary”.

Active vs. inactive

Inactive e-mails require a confirmation by the user. There are two ways of generating an inactive e-mail address:

Either way, a message will be sent to the user requesting confirmation. The e-mail contains the required information to call POST /api/session/authenticate?method=task. Upon successful completion of the confirmation process, the e-mail will become active.

It is also possible to create an active e-mail directly using _emails (needs_confirmation set to false), and it is also possible to revert the active status of an e-mail by setting needs_confirmation to true.

The confirmation request e-mail is resent in the following cases:

The confirmation codes have a certain expiration date, after which e-mails are deleted.

A requested confirmation for an email address can be cancelled by setting the write-only parameter cancel_confirmation to true. This overrules needs_confirmation.

Primary e-mail

One e-mail can be chosen as primary e-mail. This is the visible e-mail for the user. The user can set the primary e-mail using POST /api/user _new_primary_email. If the e-mail exists and is active, it will be set to be the primary; if it exists and is inactive, it will be marked to become primary when confirmed.

The administrator can change these parameters directly (is_primary, intended_primary).

When using the _new_primary_email option, the E-Mail attributes (see below) are copied from the old primary e-mail. If there is no primary e-mail, they are set as follows:

E-mail attributes

Sending e-mails

There are different kinds of e-mails:

Profile e-mails

These e-mails are sent to the primary e-mail address, if set:

Confirmation e-mails

These e-mails are sent to the e-mail address that requires confirmation

User management e-mails

These e-mails are sent to all e-mail addresses that are send_email:

Action e-mails

These e-mails are sent to the all e-mail addresses that are use_for_email: