Port #266 to 3-dev

src/sdk/cpp/1/controllers/auth/login/index.md

@@ -9,7 +9,9 @@ description: Authenticate a user
 
 Authenticates a user.
 
-## Signature
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout](/sdk/cpp/1/controllers/auth/logout) action is called, or the [jwt](/sdk/cpp/1/core-classes/kuzzle/introduction/) property is manually unset.
+
+## Arguments
 
 ```cpp
 std::string login(const std::string& strategy, const std::string& credentials);
@@ -20,15 +22,15 @@ std::string login(
     int expiresIn);
 ```
 
-## Arguments
+<br/>
 
 | Arguments     | Type                          | Description                               |
 | ------------- | ----------------------------- | ----------------------------------------- |
 | `strategy`    | <pre>const std::string&</pre> | Strategy to use                           |
 | `credentials` | <pre>const std::string&</pre> |  JSON string representing the credentials |
-| `expiresIn`   | <pre>int</pre>                |  Expiration time in milliseconds          |
+| `expiresIn`   | <pre>int</pre>                |  Expiration time, in milliseconds          |
 
-#### **_strategy_**
+#### strategy
 
 The name of the authentication [strategy](/core/1/guide/guides/kuzzle-depth/authentication/#authentication) used to log the user in.
 
@@ -37,6 +39,12 @@ The API request example on this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin](/core/1/plugins/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+
+### expiresIn
+
+The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file]({{ site_base_map }}guide/1/essentials/configuration).
+
+
 ## Return
 
 Returns the encrypted JSON Web Token.  

src/sdk/go/1/controllers/auth/login/index.md

@@ -9,21 +9,25 @@ description: Authenticate a user
 
 Authenticates a user.
 
-## Signature
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout](/sdk/go/1/controllers/auth/logout) action is called, or the [jwt](/sdk/go/1/core-structs/kuzzle/introduction/) property is manually unset.
+
+## Arguments
 
 ```go
-func (a *Auth) Login(strategy string, credentials json.RawMessage, expiresIn *int) (string, error)
+func (a *Auth) Login(
+  strategy string,
+  credentials json.RawMessage,
+  expiresIn *int) (string, error)
 ```
 
-## Arguments
 
 | Arguments     | Type   | Description                      | Required |
 | ------------- | ------ | -------------------------------- | -------- |
-| `strategy`    | string | the name of the strategy to use  | yes      |
-| `credentials` | string |  the json credentials            |  yes     |
-| `expiresIn`   | int    |  expiration time in milliseconds |  no      |
+| `strategy`    | <pre>string</pre> | Name of the strategy to use  | yes      |
+| `credentials` | <pre>string</pre> |  Credentials for that strategy            |  yes     |
+| `expiresIn`   | int    |  Expiration time, in milliseconds |  no      |
 
-#### **_strategy_**
+#### strategy
 
 The name of the authentication [strategy](/core/1/guide/guides/kuzzle-depth/authentication/#authentication) used to log the user in.
 
@@ -32,6 +36,10 @@ The API request example in this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin](/core/1/plugins/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+### expiresIn
+ The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file](/core/1/guide/guides/essentials/configuration/).
+
+
 ## Return
 
 The **login** action returns an encrypted JSON Web Token, that must then be sent in the [requests headers](/core/1/api/essentials/query-syntax/).

src/sdk/java/1/controllers/auth/login/index.md

@@ -9,29 +9,25 @@ description: Authenticate a user
 
 Authenticates a user.
 
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout](/sdk/java/1/controllers/auth/logout/) action is called, or the [jwt](/sdk/java/1/core-classes/kuzzle/constructor) property is manually unset.
+
 ## Signature
 
 ```java
-String login(
-  String,
-  String,
-  int
-);
-String login(
-  String,
-  String
-);
+String login(String, String, int expiresIn);
+String login(String, String);
 ```
+<br/>
 
 ## Arguments
 
 | Arguments     | Type   | Description                      | Required |
 | ------------- | ------ | -------------------------------- | -------- |
-| `strategy`    | String | the name of the strategy to use  | yes      |
-| `credentials` | String |  the json credentials            |  yes     |
-| `expiresIn`   | int    |  expiration time in milliseconds |  no      |
+| `strategy`    | <pre>String</pre> | Name of the strategy to use  | yes      |
+| `credentials` | <pre>String</pre> |  Credentials for that strategy            |  yes     |
+| `expiresIn`   | <pre>int</pre>    |  Token expiration time, in milliseconds |  no      |
 
-#### **_strategy_**
+#### strategy
 
 The name of the authentication [strategy](/core/1/guide/guides/kuzzle-depth/authentication/#authentication) used to log the user in.
 
@@ -40,6 +36,10 @@ The API request example in this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin](/core/1/plugins/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+### expiresIn
+
+ The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file](/core/1/guide/guides/essentials/configuration/).
+
 ## Return
 
 The **login** action returns an encrypted JSON Web Token, that must then be sent in the [requests headers](/core/1/api/essentials/query-syntax/).

src/sdk/js/6/controllers/auth/login/index.md

@@ -9,7 +9,9 @@ description: Authenticate a user
 
 Authenticates a user.
 
-<br/>
+If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout](/sdk/js/6/controllers/auth/logout/) action is called, or the [jwt](/sdk/js/6/core-classes/kuzzle/constructor/) property is manually unset.
+
+## Arguments
 
 ```javascript
 login(strategy, [credentials], [expiresIn]);
@@ -23,7 +25,7 @@ login(strategy, [credentials], [expiresIn]);
 | `credentials` | <pre>object</pre> |  Credentials for the strategy                                                          |
 | `expiresIn`   | <pre>string</pre> |  Expiration time in [ms library](https://www.npmjs.com/package/ms) format. (e.g. `2h`) |
 
-#### strategy
+### strategy
 
 The name of the [authentication strategy](/core/1/guide/guides/kuzzle-depth/authentication/) used to log the user in.
 
@@ -32,6 +34,10 @@ The API request example in this page provides the necessary arguments for the [`
 
 Check the appropriate [authentication plugin](/core/1/plugins/essentials/strategies/) documentation to get the list of additional arguments to provide.
 
+### expiresIn
+
+ The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file](/core/1/guide/guides/essentials/configuration/).
+
 ## Resolves
 
 The **login** action returns the encrypted JSON Web Token.

src/sdk/js/6/controllers/auth/refresh-token/index.md

@@ -0,0 +1,55 @@
+---
+code: true
+type: page
+title: refreshToken
+description: Refresh an authentication token
+---
+
+ # refreshToken
+
+<SinceBadge version="6.1.0" />
+
+ Refreshes a valid, non-expired authentication token.
+
+ If this action is successful, all further requests emitted by this SDK instance will use the refreshed authentication token.
+
+ ## Arguments
+
+ ```javascript
+refreshToken ([options])
+```
+
+ <br/>
+
+ | Arguments    | Type    | Description |
+|--------------|---------|-------------|
+| `options`  | <pre>object</pre> | Query options |
+
+
+ ### options
+
+ Additional query options
+
+| Property     | Type<br/>(default)    | Description   |
+| -------------- | --------- | ------------- |
+| `expiresIn` | <pre>string</pre> | Expiration time in [ms library](https://www.npmjs.com/package/ms) format. (e.g. `2h`) |
+| `queuable` | <pre>boolean</pre><br/>(`true`)| If true, queues the request during downtime, until connected to Kuzzle again |
+
+ ### expiresIn
+
+ The default value for the `expiresIn` option is defined at server level, in Kuzzle's [configuration file](/core/1/guide/guides/essentials/configuration/).
+
+ ## Resolves
+
+ The `refreshToken` action resolves to a token object with the following properties:
+
+| Property   | Type    | Description  |
+|--------------|---------|-------------|
+| `_id` | <pre>string</pre> | User unique identifier ([kuid](/core/1/guide/guides/essentials/user-authentication/#kuzzle-user-identifier-kuid)) |
+| `expiresAt` | <pre>number</pre> | Expiration timestamp in Epoch-millis format (UTC) |
+| `jwt` | <pre>string</pre> | Authentication token |
+| `ttl` | <pre>number</pre> | Time to live of the authentication token, in milliseconds |
+
+ ## Usage
+
+ <<< ./snippets/refreshToken.js

src/sdk/js/6/controllers/auth/refresh-token/snippets/refreshToken.js

@@ -0,0 +1,22 @@
+const credentials = { username: 'foo', password: 'bar' };
+
+try {
+  const jwt = await kuzzle.auth.login('local', credentials);
+
+  // Prints the encrypted authentication token
+  console.log(jwt);
+
+  // Note: to get a different token, you actually need to wait at least
+  // 1 second. Otherwise you do receive a refreshed token, but with the exact
+  // same caracteristics, as the key depends on the timestamp in Epoch format
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  // Prints:
+  // { _id: '<user kuid>',
+  //   jwt: '<a different encrypted authentication token>'
+  //   expiresAt: 1553185334220,
+  //   ttl: 3600000 }
+  console.log(await kuzzle.auth.refreshToken());
+} catch (error) {
+  console.error(error.message);
+}

src/sdk/js/6/controllers/auth/refresh-token/snippets/refreshToken.test.yml

@@ -0,0 +1,15 @@
+---
+name: auth#login
+description: Authenticate a user
+hooks:
+  before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}'
+  after: curl -X DELETE kuzzle:7512/users/foo
+template: default
+expected:
+  - ^.*\..*$
+  - "{ _id: 'foo',"
+  - ^\s*jwt: '.*\..*'
+  - ^\s*expiresAt: \d+
+  - ^\s*ttl: \d+ }
+sdk: js
+version: 6