+## Implementation
+
+### Authentication
+
+- All requests to Shaarli's API must include a **JWT token** to verify their authenticity.
+- This token must be included as an HTTP header called `Authorization: Bearer <jwt token>`.
+- JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64:
+
+```
+[header].[payload].[signature]
+```
+
+##### Header
+
+Shaarli only allow one hash algorithm, so the header will always be the same:
+
+```json
+{
+ "typ": "JWT",
+ "alg": "HS512"
+}
+```
+
+Encoded in base64, it gives:
+
+```
+ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
+```
+
+##### Payload
+
+Token expiration: To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at) field ([1](https://tools.ietf.org/html/rfc7519#section-4.1.6)). This token will be valid during **9 minutes**.
+
+```json
+{
+ "iat": 1468663519
+}
+```
+
+##### Signature
+
+The signature authenticates the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page.
+
+Example signature with PHP:
+
+```php
+$content = base64_encode($header) . '.' . base64_encode($payload);
+$signature = hash_hmac('sha512', $content, $secret);
+```
+
+
+
+## Troubleshooting
+
+### Debug mode
+
+> This should never be used in a production environment.
+
+For security reasons, authentication issues will always return an `HTTP 401` error code without any detail.
+
+It is possible to enable the debug mode in `config.json.php`
+to get the actual error message in the HTTP response body with:
+
+```json
+{
+ "dev": {
+ "debug": true
+ }
+}
+```
+
+## References
+
+- [jwt.io](https://jwt.io) (including a list of client per language).
+- [RFC - JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519)
+- [JSON Web Tokens (JWT) vs Sessions](https://float-middle.com/json-web-tokens-jwt-vs-sessions/), [HackerNews thread](https://news.ycombinator.com/item?id=11929267)
+