]>
Commit | Line | Data |
---|---|---|
53ed6d7d | 1 | ## Usage |
2 | ||
3 | See the [REST API documentation](http://shaarli.github.io/api-documentation/). | |
4 | ||
5 | ## Authentication | |
6 | ||
7 | All requests to Shaarli's API must include a JWT token to verify their authenticity. | |
8 | ||
9 | This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`. | |
10 | ||
11 | JWT resources : | |
12 | ||
43ad7c8e V |
13 | - [jwt.io](https://jwt.io) (including a list of client per language). |
14 | - RFC : https://tools.ietf.org/html/rfc7519 | |
15 | - https://float-middle.com/json-web-tokens-jwt-vs-sessions/ | |
16 | - HackerNews thread: https://news.ycombinator.com/item?id=11929267 | |
53ed6d7d | 17 | |
18 | ||
19 | ### Shaarli JWT Token | |
20 | ||
21 | JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: | |
22 | ||
23 | ``` | |
24 | [header].[payload].[signature] | |
25 | ``` | |
26 | ||
27 | #### Header | |
28 | ||
29 | Shaarli only allow one hash algorithm, so the header will always be the same: | |
30 | ||
31 | ```json | |
32 | { | |
33 | "typ": "JWT", | |
34 | "alg": "HS512" | |
35 | } | |
36 | ``` | |
37 | ||
38 | Encoded in base64, it gives: | |
39 | ||
40 | ``` | |
41 | ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== | |
42 | ``` | |
43 | ||
44 | #### Payload | |
45 | ||
46 | **Validity duration** | |
47 | ||
48 | To 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. | |
49 | ||
50 | ```json | |
51 | { | |
52 | "iat": 1468663519 | |
53 | } | |
54 | ``` | |
55 | ||
56 | See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6). | |
57 | ||
58 | ||
59 | #### Signature | |
60 | ||
61 | The 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. | |
62 | ||
63 | Signature example with PHP: | |
64 | ||
65 | ```php | |
66 | $content = base64_encode($header) . '.' . base64_encode($payload); | |
67 | $signature = hash_hmac('sha512', $content, $secret); | |
68 | ``` | |
69 | ||
70 | ||
61f63d10 V |
71 | ## Clients and examples |
72 | ### Android, Java, Kotlin | |
73 | ||
74 | - [Android client example with Kotlin](https://gitlab.com/snippets/1665808) | |
75 | by [Braincoke](https://github.com/Braincoke) | |
76 | ||
53ed6d7d | 77 | |
e62486dd V |
78 | ### PHP |
79 | ||
80 | This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library. | |
53ed6d7d | 81 | |
82 | ```php | |
e62486dd V |
83 | <?php |
84 | $baseUrl = 'https://shaarli.mydomain.net'; | |
85 | $secret = 'thats_my_api_secret'; | |
86 | ||
87 | function base64url_encode($data) { | |
88 | return rtrim(strtr(base64_encode($data), '+/', '-_'), '='); | |
89 | } | |
90 | ||
53ed6d7d | 91 | function generateToken($secret) { |
e62486dd | 92 | $header = base64url_encode('{ |
53ed6d7d | 93 | "typ": "JWT", |
94 | "alg": "HS512" | |
95 | }'); | |
e62486dd | 96 | $payload = base64url_encode('{ |
53ed6d7d | 97 | "iat": '. time() .' |
98 | }'); | |
e62486dd V |
99 | $signature = base64url_encode(hash_hmac('sha512', $header .'.'. $payload , $secret, true)); |
100 | return $header . '.' . $payload . '.' . $signature; | |
53ed6d7d | 101 | } |
102 | ||
53ed6d7d | 103 | |
e62486dd V |
104 | function getInfo($baseUrl, $secret) { |
105 | $token = generateToken($secret); | |
106 | $endpoint = rtrim($baseUrl, '/') . '/api/v1/info'; | |
53ed6d7d | 107 | |
e62486dd V |
108 | $headers = [ |
109 | 'Content-Type: text/plain; charset=UTF-8', | |
110 | 'Authorization: Bearer ' . $token, | |
111 | ]; | |
112 | ||
113 | $ch = curl_init($endpoint); | |
114 | curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); | |
115 | curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); | |
116 | curl_setopt($ch, CURLOPT_AUTOREFERER, 1); | |
117 | curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1); | |
118 | ||
119 | $result = curl_exec($ch); | |
120 | curl_close($ch); | |
121 | ||
122 | return $result; | |
123 | } | |
124 | ||
125 | var_dump(getInfo($baseUrl, $secret)); | |
53ed6d7d | 126 | ``` |
61f63d10 V |
127 | |
128 | ||
129 | ### Python | |
130 | ||
131 | See the reference API client: | |
132 | ||
133 | - [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs | |
134 | - [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github |