Authentication

For authentication JSON Web Tokens (JWT) are used.

JSON Web Tokens (JWT)

Acquiring a token

A JWT token can be acquired by posting a user’s credentials to the @login endpoint.

POST /@login HTTP/1.1
Accept: application/json

{
  "login": "admin",
  "password": "admin"
}

The server responds with a JSON object containing the token.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzNjE3NDIsImV4cCI6MTY0OTQwNDk0Mn0.SBqYCkWsHNHqzTUPIGC1c1Zd9iDARmqDecb3k7Ok7vE"
}

If you send incorrect credentials you will get notified.

POST /@login HTTP/1.1
Accept: application/json

{
  "login": "admin",
  "password": "wrong"
}


HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "type": "Invalid credentials",
        "message": "Wrong login and/or password."
    }
}

If you send credentials for a non-existing user you will also get notified.

POST /@login HTTP/1.1
Accept: application/json

{
  "login": "doesntexist",
  "password": "wrong"
}


HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": {
        "type": "Invalid credentials",
        "message": "Wrong login and/or password."
    }
}

When you don’t set all the required fields you will get an error message.

POST /@login HTTP/1.1
Accept: application/json

{
  "login": "admin"
}


HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": {
        "type": "Missing credentials",
        "message": "Login and password must be provided in body."
    }
}

Authenticating with a token

The token can now be used in subsequent requests by including it in the Authorization header with the Bearer scheme:

POST /@login-renew HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Renewing a token

By default the token will expire after 12 hours and thus must be renewed before expiration. To renew the token simply post to the @login-renew endpoint.

POST /@login-renew HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

The server returns a JSON object with a new token:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzNjE3NDIsImV4cCI6MTY0OTQwNDk0Mn0.SBqYCkWsHNHqzTUPIGC1c1Zd9iDARmqDecb3k7Ok7vE"
}

When you don’t provide a session or your session is incorrect:

POST /@login-renew HTTP/1.1

The server responds with an error message:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "type": "Invalid session",
    "message": "User is not logged in."
  }
}

Invalidating a token

The @logout endpoint can be used to invalidate tokens. However by default tokens are not persisted on the server and thus can not be invalidated.

The logout request must contain the existing token in the Authorization header.

POST /@logout HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

If invalidation succeeds, the server responds with an empty 204 reponse:

HTTP/1.1 204 No Content

Permissions

In order for a user to use the REST API you need common permissions depending on the particular service. For example, retrieving a resource using GET will require View, adding an object using POST will require Add, and so on.