Under the hood: Authentication (login)

In the second post of ‘Under the hood’, I’ll explain how our current login system works and how you can use it. This is mainly interesting if you want to know how to get API-access to recourses which need a login in the future.


First a bit about the overall architecture.

Loklak uses an embedded Jetty HTTP server. It works fundamentaly different than for example, an Apache server with PHP.

Like in Apache, you can have a folder with static content, like hmtl, css and js files, which just get displayed. But for dynamic output, you don’t have just java-class-files in the same folder, which get interpretated on the fly like php-files do.

Instead we register so called servlets on the server before we start it. This servlets are java classes which get a http-request as input and send a response at the end. All classes in the api-packages are such servlets.

So the idea is to create a so called AAA-system:

  • Authentication (who are you?)
  • Authorization (what are you allowed to do?)
  • Accounting (what/how much did you do already?)

As of now, only the authentication part is ready to use, authorization will follow soon (hopefully early next week)

To make it easy for the servlets have access to that system, Michael created an abstract class called AbstactAPIHandler. This class is meant to contain all common code the servlets need, which in turn extend this class to implement the actual functionality.

So what does it offer so far? Well, as of the authentication, there’s alot of different use cases how we want to be able to authenticate a user:

  1. Login via a user id and a password
  2. For browsers: sessions and cookies, so the user stays logged in over multiple requests
  3. For api-access and links: access tokens
  4. Login via a key-pair (not yet implemented)

1., to 3. are implemented and ready to use. Here’s how:

User id and password

Just add

[email protected]&password=123456

to a request to any sevlet extending AbstractAPIHandler. This will log you in as the user [email protected]

As we want to use this for browser logins and logins via other tools (for example curl), this does not create a session.  A session means the server remembers you over multiple calls. We don’t want that for pure API calls, as APIs are better stateless, that means all calls are independent from each other.

Sessions and Cookies

If you use a browser, you probably want to do the login only once. Afterwards, your browser and the server should remember each other.

There are two different ways to archive that:

  • Sessions, which are short-lived and forgotten as soon as either the browser or the server shuts down
  • Cookies, which can live for a longer time and survice restarts (in the moment, server restarts also remove them, but this will change in the future)

Technically, these are very similar, but a bit different in how we have to use them.

Anyhow, you can request a session or a cookie with:




respectively. Cookie currently expire after one week if not used.


In some use-cases you might want to log in without appending you password each time. For example you want to create link which logs a user in (this is done with the email validation link).

Or you want stateles API-access via a public-private key login (which is somewhat slow).

Then it’s useful to create a access-token. Currently you can do so by calling handshake-client.json. An example:

domain.com/api/[email protected]&password=123456&valid_seconds=3600

This returns a access-token for the user [email protected] with a livetime of one hour. You can then use that token to make further queries:



That’s it for the login, but I’ll add more as soon as public-private-key login is ready.

Under the hood: Authentication (login)