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: 192.168.1.100:8001
        Content-Type: application/json
        {
            "data": {
                "attributes":
                {
                    "username": "myuser",
                    "password": "MyPass1298"
                },
                "type": "session"
            }
        }

        import requests
        
        url = "http://192.168.1.100:8001/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"
            }
        }