JSON API¶

Authentication¶

Authentication is done by providing a valid Authentication Session identifier. An Authentication Session identifier is a 16 bytes value encoded as 32 characters string, for example 122813edb8dea90702d2bffb90cf3e8b.

Authentication Session identifier must be presented either by using HTTP Authorization header or a HTTP cookie.

When Authorization header is used, Bearer auth schema is expected, for example Authorization: Bearer 122813edb8dea90702d2bffb90cf3e8b.

When cookie is used, s key should be set to the identifier value, for example Cookie: s=122813edb8dea90702d2bffb90cf3e8b.

Error response¶

There are two formats an error message can follow, depending on the cause.

General error¶

If error response is caused by a non validation related issue, general error schema is used to format the response payload.

{
  "error": "Human readable error description."
}

Validation error¶

If error response is caused by an incomplete or an invalid input data, a validation error schema is used to format the response payload.

{
  "validation": {
    "email": [
      "Required."
    ],
    "password": [
      "Must be at least 12 characters long.",
      "Must meet complexity requirements."
    ]
  }
}

Authentication Session management¶

Create a new Authentication Session¶

POST /sessions¶

To create a new Authentication Session, send you authentication credentials. If Two-Factor authentication is enabled, you must additionally send a generated Time-based One-Time Password code.

Example request:

POST /sessions HTTP/1.1
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "admin",
  "code": "123456"
}

Request JSON Object

email (string) – The email used to register the account.
password (string) – The account password in plain text.
code (string) – Required if two-factor is enabled. A generated, 6-digit TOTP token.

Example response body:

{
  "account_id": "1ad4ce82183f3c5027a96883bac1d7e2",
  "session_id": "122813edb8dea90702d2bffb90cf3e8b",
  "permissions": [
    "lith-admin",
    "login"
  ]
}

Response JSON Object

account_id (string) – The identifier of the account that this authentication session represents.
session_id (string) – The identifier of this authentication session.
permissions (list of strings) – A list of permissions that this session grants.

Status Codes

201 Created – An Authentication Session was successfully created.
400 Bad Request – Incomplete, invalid or malformed JSON payload. See Error response section for details.
403 Forbidden – Account cannot login due to missing permissions.

Introspect an existing Authentication Session¶

GET /sessions¶

An existing Authentication Session can be introspected.

Example request:

GET /sessions HTTP/1.1
Authorization: Bearer 122813edb8dea90702d2bffb90cf3e8b

Example response body:

{
  "account_id": "1ad4ce82183f3c5027a96883bac1d7e2",
  "session_id": "122813edb8dea90702d2bffb90cf3e8b",
  "permissions": [
    "lith-admin",
    "login"
  ]
}

Response JSON Object

account_id (string) – The identifier of the account that this authentication session represents.
session_id (string) – The identifier of this authentication session.
permissions (list of strings) – A list of permissions that this session grants.

Status Codes

200 OK – Authentication Session is valid and was successfully introspected.
401 Unauthorized – A valid Authentication Session was not provided.

Terminate an existing Authentication Session¶

DELETE /sessions¶

An existing Authentication Session can be terminated.

Example request:

DELETE /sessions HTTP/1.1
Authorization: Bearer 122813edb8dea90702d2bffb90cf3e8b

Status Codes

204 No Content – Authentication Session is valid and was successfully deleted.
401 Unauthorized – A valid Authentication Session was not provided.

DELETE /sessions¶

To terminate all existing Authentication Session that belong to an account, send JSON serialized {"all": true} payload as the request body. Account is determined by the session token provided during authentication.

Example request:

DELETE /sessions HTTP/1.1
Authorization: Bearer 122813edb8dea90702d2bffb90cf3e8b
Content-Type: application/json
Content-Lenth: 13

{"all": true}

Status Codes

204 No Content – All Authentication Sessions were successfully deleted.
401 Unauthorized – A valid Authentication Session was not provided.

Two Factor authentication¶

Currently, Lith supports only Time-based One-Time Passwords as the second factor.

It is recommended to use an application on your phone to manage and generate TOTP tokens.

Check if Two-Factor authentication is enabled¶

GET /twofactor¶

User can check if two-factor authentication is enabled for the account.

Example request:

GET /twofactor HTTP/1.1
Authorization: Bearer 122813edb8dea90702d2bffb90cf3e8b

Example response body:

{
  "enabled": false
}

Response JSON Object

enabled (boolean) – True if two-factor authentication is enabled and required.

Status Codes

200 OK – A successful response contains information if the two-factor authentication is enabled for this account.
401 Unauthorized – A valid Authentication Session was not provided.

Enable Two-Factor authentication¶

POST /twofactor¶

Any account can enable two-factor authentication. Once enabled, two-factor authentication secret cannot be changed or deleted.

Example request:

POST /twofactor HTTP/1.1
Authorization: Bearer 122813edb8dea90702d2bffb90cf3e8b
Content-Type: application/json

{
  "secret": "base32-encoded-data",
  "code": "123456"
}

Request JSON Object

secret (string) – A base32 encoded secret value.
code (string) – The current TOTP code generated using secret.

In order to enable two-factor authentication, you must authenticate. If two-factor authentication is required, you can no longer create a new authentication session. If this is the case, only for this endpoint, you can directly send your email and password as an alternative authentication method.

Example request:

POST /twofactor HTTP/1.1
Content-Type: application/json

{
  "secret": "base32-encoded-data",
  "code": "123456",
  "email": "user@example.com",
  "password": "t0pSecret"
}

Request JSON Object

secret (string) – A base32 encoded secret value.
code (string) – The current, 6-digit TOTP code generated using provided secret.
email (string) – An email address used for the account registration.
password (string) – Account password in plain text.

Status Codes

201 Created – Two-factor authentication was successfully enabled for this account. No payload is returned.
400 Bad Request – An incomplete or malformed input. See Error response section for details.
401 Unauthorized – A valid authentication credentials were not provided.
409 Conflict – Two-factor authentication is already enabled for this account.

Account management¶

Create a new account¶

POST /accounts¶

Account creation is a two step operation and require email address confirmation.

First, you must submit your email address that you would like to use to register a new account. After this, you will receive an email message with a link to finish registration process.

Example request:

POST /accounts HTTP/1.1
Content-Type: application/json

{
  "email": "user@example.com"
}

Request JSON Object

email (string) – An email address that should be used to authenticate.

Status Codes

202 Accepted – Registration was initialized, email message with a one-time registration token was sent. No response payload.
400 Bad Request – Incomplete, invalid or malformed JSON payload.
409 Conflict – Provided email is already used by another account.

PUT /accounts¶

Received email message will contain a URL with one-time registration token. Your application is responsible for handling that URL and extracting registration token.

Example request:

PUT /accounts HTTP/1.1
Content-Type: application/json

{
  "password": "t0pSecret",
  "token": "fdf1033a39a0ffae50784b44909a97bd"
}

Request JSON Object

password (string) – A plain text password that will be set for this account.
token (string) – The one-time token sent via email.

Example response body:

{
  "account_id": "8138177c4fa45ce839d158374d1601c9"
}

Response JSON Object

account_id (string) – The identifier of the newly created account.

Status Codes

201 Created – Successful registration. New account email/password combination can be used to login.
400 Bad Request – Incomplete, invalid or malformed JSON payload.
401 Unauthorized – Provided one-time token is invalid or expired.
409 Conflict – Provided email is already used by another account.

Reset an account password¶

POST /passwordreset¶

Account password reset is a two step operation.

Example request:

POST /passwordreset HTTP/1.1
Content-Type: application/json

{
  "email": "user@example.com"
}

Response JSON Object

email (string) – The email address connected to the account we want to access.

Status Codes

202 Accepted – Password reset was initialized, email message with a one-time token was sent. No response payload.
400 Bad Request – Incomplete, invalid or malformed JSON payload.

PUT /passwordreset¶

Example request:

PUT /passwordreset HTTP/1.1
Content-Type: application/json

{
  "password": "t0pSecret",
  "token": "fdf1033a39a0ffae50784b44909a97bd"
}

Request JSON Object

password (string) – A plain text password that will be set for this account.
token (string) – The one-time token sent via email.

Example response body:

{
  "account_id": "8138177c4fa45ce839d158374d1601c9"
}

Response JSON Object

account_id (string) – The identifier of the newly created account.

Status Codes

200 OK – A new account password is set.
401 Unauthorized – Provided one-time token is invalid or expired.
409 Conflict – Account email address has changed since the one-time token was generated. You must request a new password reset token.

Lith documentation

JSON API

Contents

JSON API¶

Authentication¶

Error response¶

General error¶

Validation error¶

Authentication Session management¶

Create a new Authentication Session¶

Introspect an existing Authentication Session¶

Terminate an existing Authentication Session¶

Two Factor authentication¶

Check if Two-Factor authentication is enabled¶

Enable Two-Factor authentication¶

Account management¶

Create a new account¶

Reset an account password¶