Create Session

On This Page

Description

Creates a new management session. The operation returns a session cookie that can be used to authenticate the user when sending other management requests (see the description of the <cookie> parameter in the General Management-API Structure documentation).

The cookie is valid for the duration of its time-to-live (TTL) period, which is returned in the operation's response (both in the max-age parameter of the Set-Cookie response header, and in the ttl response-data attribute). When this period elapses, the cookie expires. The cookie's expiration time is returned in the expires_at response-data attribute.

Create Session itself doesn't require a session cookie.

Request

Request Header

Syntax

POST /api/sessions HTTP/1.1
Host: <management-APIs URL>
Content-Type: application/json

url = "<management-APIs URL>/api/sessions"
headers = { "Content-Type": "application/json" }

HTTP Method

POST

URL Resource Parameters

None

Request Data

Syntax

{
    "data": {
        "attributes": {
            "username": "string",
            "password": "string"
        },
        "type": "session"
    }
}

payload = {
            "data": {
                "attributes": {
                    "username": "string",
                    "password": "string"
                },
                "type": "session"
            }
          }

Parameters

attributes

User-credentials attributes, as received from your platform's security administrator (see security_admin).

Type: A JSON object of user-credentials attributes

Requirement: Required

The following user-credentials attributes are applicable to this request:

username

User name.

Type: String

Requirement: Required

password

Password.

Type: String

Requirement: Required

type

The type of the data object. This value must be set to "session".

Type: String

Requirement: Required

Response

Response Header

Syntax

HTTP/1.1 <status code; 201 on success> <reason phrase>
Content-Type: application/json
Set-Cookie: session=<cookie>; max-age=<age>; path=/;
...

The Set-Cookie response header contains the new session cookie that you created (<cookie>). Save this cookie and use it to submit requests to other management-API resources (see the Sessions API overview and Create Session description.

Response Data

Syntax

{
    "data": {
        "attributes": {
            "created_at": "string",
            "expires_at": number,
            "gids": [
                "string"
            ],
            "group_ids": [
                "string"
            ],
            "plane":  "string",
            "ttl":    number,
            "uid":    number
        },
        "id": "string",
        "relationships": {
            "tenant": {
                "data": {
                    "id":   "string",
                    "type": "string"
                }
            },
            "user": {
                "id":   "string",
                "type": "string"
            }
        },
        "type": "session"
    }
}

Elements

The data object in the HTTP response body contains information about the new session, such as its creation time (created_at attribute), expiration time (expires_at attribute), and time-to-live period in seconds (ttl). Full the full list of returned data elements, see response-data syntax above.

Examples

Request

POST /api/sessions HTTP/1.1
Host: https://dashboard.default-tenant.app.mycluster.iguazio.com
Content-Type: application/json

{
    "data": {
        "attributes":
        {
            "username": "myuser",
            "password": "MyPass1298"
        },
        "type": "session"
    }
}

import requests

url = "https://dashboard.default-tenant.app.mycluster.iguazio.com/api/sessions"
headers = {"Content-Type": "application/json"}
payload = {
            "data": {
                "attributes": {
                    "username": "myuser",
                    "password": "MyPass1298"
                },
                "type": "session"
            }
          }

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Response

HTTP/1.1 201 Created
Content-Type: application/json
Date: Mon, 18 Mar 2019 00:48:30 GMT
Set-Cookie: session=j%3A%7B%22sid%22%3A%20%22240e02ed-2204-4f30-abce-52ebd8456d94%22%7D; max-age=86400; path=/;
Transfer-Encoding: chunked

{
    "data": {
        "relationships": {
            "user": {
                "data": {
                    "type": "user",
                    "id": "6e040a9a-9403-44bd-8f90-a61e079c6c45"
                }
            },
            "tenant": {
                "data": {
                    "type": "tenant",
                    "id": "b7c663b1-a8ee-49a9-ad62-ceae7e751ec8"
                }
            }
        },
        "attributes": {
            "kind": "session",
            "group_ids": [],
            "uid": 0,
            "gids": [
                65534
            ],
            "tenant_id": "b7c663b1-a8ee-49a9-ad62-ceae7e751ec8",
            "created_at": "2019-03-18T00:48:30.614000+00:00",
            "expires_at": 1552956510,
            "plane": "control",
            "ttl": 86400
        },
        "type": "session",
        "id": "290818d2-1ded-4c9c-beeb-0940f8dcf0a5"
    }
}

Using Postman

To send a Create Session request using Postman, follow these steps:

Create a new request and set the request method to POST.
In the request URL field, enter the following; replace <management-APIs URL> with the HTTPS URL of the platform dashboard:
```
<management-APIs URL>/api/sessions/
```
For example:
```
https://dashboard.default-tenant.app.mycluster.iguazio.com/api/sessions/
```
In the Headers tab, add a Content-Type header (Key) and set its value to application/json.

In the Body tab, select the raw format and add the following JSON code; replace the <username> and <password> placeholders with your platform login credentials:

{
    "data": {
        "attributes": {
            "username": "<username>",
            "password": "<password>"
        },
        "type": "session"
    }
}

Select Send to send the request, and then check the response. In the case of a successful request —
- The Headers response tab contains a Set-Cookie header with a session element whose value is the session cookie (session=<cookie>). You can also see the cookie in the Cookies response tab (for example, j%3A%7B%22sid%22%3A%20%22a9ce242a-670f-47a8-9c8b-c6730f2794dc%22%7D). Copy and save this cookie. You'll need to pass it as the value of the session parameter of the Cookie header in other management-API requests.
- The Set-Cookie header also contains a max-age element, which contains the session's time-to-live (TTL) period, in seconds; when this period elapses, the session expires and the cookie is no longer valid. The same value is also returned in the data.attributes.ttl response-body data element, which you can see in the Body tab.
- In the Body tab, you can see the full JSON response data. Among the returned response-data attributes is a ttl attribute that contains the same session TTL value that's returned in the max-age header parameter, and an expires_at attribute that contains the session's expiration time as a Unix timestamp in seconds. The expiration time can also be seen as a date format in the Expires column of the Cookies response tab.