aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/REST-API.md
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2017-05-07 18:45:02 +0200
committerGitHub <noreply@github.com>2017-05-07 18:45:02 +0200
commit510f7233006e9ea2e0d653049e2ff62537a4fda8 (patch)
tree90af6fbddda19c22c1bd21e2fc6ed135116cce48 /doc/REST-API.md
parentf501caed215bd12caced5106f9226638b2b15fb4 (diff)
parentb230bf207df576fa2ad165702184edf21f674ce7 (diff)
downloadShaarli-510f7233006e9ea2e0d653049e2ff62537a4fda8.tar.gz
Shaarli-510f7233006e9ea2e0d653049e2ff62537a4fda8.tar.zst
Shaarli-510f7233006e9ea2e0d653049e2ff62537a4fda8.zip
Merge pull request #863 from ArthurHoaro/v0.9.0
Bump version to v0.9.0
Diffstat (limited to 'doc/REST-API.md')
-rw-r--r--doc/REST-API.md105
1 files changed, 105 insertions, 0 deletions
diff --git a/doc/REST-API.md b/doc/REST-API.md
new file mode 100644
index 00000000..d7909978
--- /dev/null
+++ b/doc/REST-API.md
@@ -0,0 +1,105 @@
1#REST API
2## Usage
3
4See the [REST API documentation](http://shaarli.github.io/api-documentation/).[](.html)
5
6## Authentication
7
8All requests to Shaarli's API must include a JWT token to verify their authenticity.
9
10This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`.
11
12JWT resources :
13
14 * [jwt.io](https://jwt.io) (including a list of client per language).[](.html)
15 * RFC : https://tools.ietf.org/html/rfc7519
16 * https://float-middle.com/json-web-tokens-jwt-vs-sessions/
17 * HackerNews thread: https://news.ycombinator.com/item?id=11929267
18
19
20### Shaarli JWT Token
21
22JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64:
23
24```
25[header].[payload].[signature][](.html)
26```
27
28#### Header
29
30Shaarli only allow one hash algorithm, so the header will always be the same:
31
32```json
33{
34 "typ": "JWT",
35 "alg": "HS512"
36}
37```
38
39Encoded in base64, it gives:
40
41```
42ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
43```
44
45#### Payload
46
47**Validity duration**
48
49To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes.
50
51```json
52{
53 "iat": 1468663519
54}
55```
56
57See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).[](.html)
58
59
60#### Signature
61
62The signature authenticate 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.
63
64Signature example with PHP:
65
66```php
67$content = base64_encode($header) . '.' . base64_encode($payload);
68$signature = hash_hmac('sha512', $content, $secret);
69```
70
71
72### Complete example
73
74#### PHP
75
76```php
77function generateToken($secret) {
78 $header = base64_encode('{
79 "typ": "JWT",
80 "alg": "HS512"
81 }');
82 $payload = base64_encode('{
83 "iat": '. time() .'
84 }');
85 $signature = hash_hmac('sha512', $header .'.'. $payload , $secret);
86 return $header .'.'. $payload .'.'. $signature;
87}
88
89$secret = 'mysecret';
90$token = generateToken($secret);
91echo $token;
92```
93
94> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68`
95
96```php
97$options = [[](.html)
98 'http' => [[](.html)
99 'method' => 'GET',
100 'jwt' => $token,
101 ],
102];
103$context = stream_context_create($options);
104file_get_contents($apiEndpoint, false, $context);
105```