]>
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 | ||
e62486dd | 71 | ### Complete examples |
53ed6d7d | 72 | |
e62486dd V |
73 | ### PHP |
74 | ||
75 | This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library. | |
53ed6d7d | 76 | |
77 | ```php | |
e62486dd V |
78 | <?php |
79 | $baseUrl = 'https://shaarli.mydomain.net'; | |
80 | $secret = 'thats_my_api_secret'; | |
81 | ||
82 | function base64url_encode($data) { | |
83 | return rtrim(strtr(base64_encode($data), '+/', '-_'), '='); | |
84 | } | |
85 | ||
53ed6d7d | 86 | function generateToken($secret) { |
e62486dd | 87 | $header = base64url_encode('{ |
53ed6d7d | 88 | "typ": "JWT", |
89 | "alg": "HS512" | |
90 | }'); | |
e62486dd | 91 | $payload = base64url_encode('{ |
53ed6d7d | 92 | "iat": '. time() .' |
93 | }'); | |
e62486dd V |
94 | $signature = base64url_encode(hash_hmac('sha512', $header .'.'. $payload , $secret, true)); |
95 | return $header . '.' . $payload . '.' . $signature; | |
53ed6d7d | 96 | } |
97 | ||
53ed6d7d | 98 | |
e62486dd V |
99 | function getInfo($baseUrl, $secret) { |
100 | $token = generateToken($secret); | |
101 | $endpoint = rtrim($baseUrl, '/') . '/api/v1/info'; | |
53ed6d7d | 102 | |
e62486dd V |
103 | $headers = [ |
104 | 'Content-Type: text/plain; charset=UTF-8', | |
105 | 'Authorization: Bearer ' . $token, | |
106 | ]; | |
107 | ||
108 | $ch = curl_init($endpoint); | |
109 | curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); | |
110 | curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); | |
111 | curl_setopt($ch, CURLOPT_AUTOREFERER, 1); | |
112 | curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1); | |
113 | ||
114 | $result = curl_exec($ch); | |
115 | curl_close($ch); | |
116 | ||
117 | return $result; | |
118 | } | |
119 | ||
120 | var_dump(getInfo($baseUrl, $secret)); | |
53ed6d7d | 121 | ``` |