From a3279958ad1a6e16e31049f8871ae2d211faec6b Mon Sep 17 00:00:00 2001
From: Mattia Dal Ben <mattdibi@users.noreply.github.com>
Date: Tue, 14 Nov 2023 12:39:22 +0100
Subject: [PATCH] docs: add Session v1 login example using `curl` (#4975)

* docs: add Session v1 login example using `curl`

* docs: fix typo

* style: formatting

(cherry picked from commit e9116f905365f17e4ff876de574104bf0f95f858)
---
 docs/references/rest-apis/rest-session-api.md | 59 ++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/docs/references/rest-apis/rest-session-api.md b/docs/references/rest-apis/rest-session-api.md
index 1496277ff38..3c09f4444f8 100644
--- a/docs/references/rest-apis/rest-session-api.md
+++ b/docs/references/rest-apis/rest-session-api.md
@@ -21,6 +21,63 @@ The supported workflows are the following:
 
 4. Access the desired resources, set the XSRF token previously obtained as the value of the `X-XSRF-Token` HTTP header on each request. If a reuqest fails with error code 401, proceed to step 2.
 
+#### Login example with `curl`
+
+##### 1. Login with username/password and collect the session cookie
+
+```bash
+curl -k -X POST \
+    -H 'Content-Type: application/json' \
+    https://$ADDRESS/services/session/v1/login/password \
+    -d '{"password": "$KURA_PASS", "username": "$KURA_USER"}' -v
+```
+
+where:
+
+- `$ADDRESS`: is the address of the Kura instance
+- `$KURA_USER`: is the Kura username
+- `$KURA_PASS`: is the Kura password
+
+in the log you should find a `JSESSIONID` you'll use in subsequent reqeusts
+
+```
+...
+< HTTP/1.1 200 OK
+< Date: Tue, 14 Nov 2023 08:17:26 GMT
+< Set-Cookie: JSESSIONID=myawesomecookie; Path=/; Secure; HttpOnly
+< Expires: Thu, 01 Jan 1970 00:00:00 GMT
+< Content-Type: application/json
+< Content-Length: 30
+<
+* Connection #0 to host 192.168.1.111 left intact
+{"passwordChangeNeeded":false}%
+```
+
+##### 2. Retrieve the XSRF token
+
+```bash
+curl -k -X GET \
+    -b "JSESSIONID=myawesomecookie" \
+    https://$ADDRESS/services/session/v1/xsrfToken
+```
+
+in the response you'll find your XSRF token you'll need to use in subsequent requests
+
+```
+{"xsrfToken":"myawesometoken"}%
+```
+
+##### 3. Access the resource
+
+Using the Cookie and the XSRF token you just retrieved you can access your desired resource
+
+```bash
+curl -k -X GET \
+    -H 'X-XSRF-Token: myawesometoken' \
+    -b "JSESSIONID=myawesomecookie" \
+    https://$ADDRESS/services/deploy/v2/
+```
+
 ### Update password workflow
 
 1. Get an XSRF token using the [GET/xsrfToken](#getxsrftoken) endpoint.
@@ -324,4 +381,4 @@ An object reporting a failure message.
 <br>**Properties**:
 
   * **message**: `string` 
-      A message describing the failure.
\ No newline at end of file
+      A message describing the failure.