]>
Commit | Line | Data |
---|---|---|
b230bf20 A |
1 | #REST API |
2 | ## Usage | |
3 | ||
4 | See the [REST API documentation](http://shaarli.github.io/api-documentation/).[](.html) | |
5 | ||
6 | ## Authentication | |
7 | ||
8 | All requests to Shaarli's API must include a JWT token to verify their authenticity. | |
9 | ||
10 | This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`. | |
11 | ||
12 | JWT 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 | ||
22 | JWT 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 | ||
30 | Shaarli 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 | ||
39 | Encoded in base64, it gives: | |
40 | ||
41 | ``` | |
42 | ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== | |
43 | ``` | |
44 | ||
45 | #### Payload | |
46 | ||
47 | **Validity duration** | |
48 | ||
49 | 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. | |
50 | ||
51 | ```json | |
52 | { | |
53 | "iat": 1468663519 | |
54 | } | |
55 | ``` | |
56 | ||
57 | See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).[](.html) | |
58 | ||
59 | ||
60 | #### Signature | |
61 | ||
62 | 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. | |
63 | ||
64 | Signature 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 | |
77 | function 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); | |
91 | echo $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); | |
104 | file_get_contents($apiEndpoint, false, $context); | |
105 | ``` |