System API

Any operation doable via the front-end application is doable via the API; either a single endpoint or a combination of.

The system API is responsible for core system resources such as users and roles. It is also responsible for core operations such as authentication.

Whenever an operation affects the system and is not specific to any of our applications, you will most likely need to use the system API

We omit most of the data returned by these endpoints. We replace the important data with variables, such as $JWT so that we can copy-paste these examples over any environment.

  • URL path: /system,

  • alias: $SystemAPI,

Authenticating users

To authenticate the user with their login credentials (email - $USER_EMAIL; password - $USER_PASSWORD), we use the POST $SystemAPI/auth/internal/login endpoint.

The response is the following JSON object:

{
  "jwt": "$JWT",
  "user": {
    "userID": "$USER_ID",
    "name": "$USER_NAME",
    "email": "$USER_EMAIL",
    "username": "$USER_USERNAME",
    "handle": "$USER_HANDLE"
  }
}

The received $JWT token can be used for authenticating API requests.

The $JWT token is bearer, so you must prefix it with Bearer, so for example Bearer $JWT.

Example request

curl "$SystemAPI/auth/internal/login" \
 --data-binary "{\"email\":\"$USER_EMAIL\",\"password\":\"$USER_PASSWORD\"}";

Example response

{
  "response": {
    "jwt": "$JWT",
    "user": {
      "userID": "$USER_ID",
      "name": "$USER_NAME",
      "email": "$USER_EMAIL",
      "username": "$USER_USERNAME",
      "handle": "$USER_HANDLE"
    }
  }
}