Sessions (sessions)

Requests

HTTP verb Endpoint Description

POST

/rest/v1/iam/sessions

Creating a session (login)

GET

/rest/v1/iam/sessions/current

Getting current session data

PATCH

/rest/v1/iam/sessions/current

Modifying the current session

DELETE

/rest/v1/iam/sessions/current

Deleting the current session (logout)

DELETE

/rest/v1/iam/sessions/others

Deleting the user’s other sessions

Creating a session (login)

Authenticates the user in the domain, creates a session and sets a cookie (EraSession), or returns a token (session_token) in the response.

Subsequently all requests containing the EraSession cookie with the session identifier are associated with this session. If session_type is specified, the client (web application) receives a token (session_token) in the response, must read and remember it, and then send the header Authorization: Bearer <session_id> for API requests in the context of this individual session.

Applies an IP address ban filter to counter account brute-forcing. Rejects the request without processing if within the previous 3 minutes 5 failed authorization attempts occurred (an incorrect combination of domain, login, pwd parameters).

When requests with a nonexistent session identifier arrive, applies the ban filter by the same rules.

Request

Table 1. Request parameters
Specification Description

Name: domain
Type: str

Domain for authorization.

Name: login
Type: str

User account login in the domain.

Name: pwd
Type: str

User account password in the domain.

Name: session_type
Type: str
Default: absent

Type of session to create. Possible values:

  • 'token' – an individual session will be created, its identifier returned in the response body instead of the cookie header. Subsequently this value should be passed in the header "Authorization: Bearer TOKEN".

  • 'token_clone_cookie' – opens a new session by copying credentials from the cookie session (which the browser sends automatically). If specified, the 'domain', 'login', 'pwd' parameters are not required and are ignored.

  • 'cookie' - a standard session will be created and set in the cookie header.

  • if the value is absent, it is equivalent to 'cookie'

Name: token
Type: str
Default: absent

External token. If the parameter is set, then instead of password verification the service script for external token verification installed in the system is run (master domain parameter 'iam_token_svcscript_code'). The 'domain', 'login', 'pwd' parameters are not required and are ignored. To confirm authentication, the script must return in specially named variables the name of an existing domain and the login of a user existing in the domain.

Example request to create a session
POST /rest/v1/iam/sessions HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "domain": "docs.rootdomain.ru",
  "login": "peter",
  "pwd": "123"
}
Example request to create an individual session
POST /rest/v1/iam/sessions HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "session_type": "token",
  "domain": "kzn.tele.dom",
  "login": "username",
  "pwd": "userpass"
}
Example request to clone a cookie session into an individual one
POST /rest/v1/iam/sessions HTTP/1.1
Cookie: EraSession=07f49a96-0178-a220-2e37-e0d55e0cd303
Content-Type: application/json; charset=utf-8

{
  "session_type": "token_clone_cookie"
}

Response

Session creation
HTTP/1.1 204 No Content
set-cookie: EraSession=6ef97511-0178-a21d-bd9a-e0d55e0cd303; Expires=Mon, 19 Apr 2021 12:59:21 GMT; Path=/; SameSite=Strict; Secure; HttpOnly
Individual session creation or cloning
HTTP/1.1 200 OK

{
  "session_token": "e2479460-0174-01d8-6638-e0d55e0cd13e"
}

Getting current session data

The session is identified first by token (Authorization header) if present and valid (lifetime has not expired), otherwise by cookie.

Returns data for the current session:

Field Type Description

domain

str

current domain name

domain_is_master

bool

true if the current domain is the master, otherwise false

domains

array<object>

list of domains to which the user can switch without additional authorization

login

str

authorized user login

name

str

authorized user name

name_login

str

single string containing the authorized user’s name and login

roles

array<str>

list of authorized user roles in the current domain

solution

str

current domain type (constant type 'era' or 'master').

tags

array<str>

tags of the authorized user account

user_id

uuid

authorized user identifier

webapps

array<object>

list of web applications available to the authorized user

The domains field. Each domain is specified as an object:

Field Type Description

domain

str

domain name

is_master

bool

true if the domain is the master, otherwise false

The webapps field. Each web application is specified as an object:

Field Type Description

name

str

application name

description

str

application description

order

int

output order

icon

str

URL of the application icon resource

fa-icon

str

font-awesome format icon name

roles

array<str>

list of user roles that can access the application

url

str

URL of the application launch point

Web application objects may contain additional fields supplied directly from metadata files (webapps.json in the metadata folder for system applications and in the role application metadata file).

Request

Example request
GET /rest/v1/iam/sessions/current HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "domain": "docs.rootdomain.ru",
  "domain_is_master": false,
  "domains": [
    {
      "domain": "rootdomain.ru",
      "is_master": true
    },
    {
      "domain": "test.rootdomain.ru",
      "is_master": false
    }
  ],
  "login": "peter",
  "name": "Peter Bukashin",
  "name_login": "Peter Bukashin (peter)",
  "roles": [
    "admin"
  ],
  "solution": "incoplax",
  "tags": [],
  "user_id": "71374fef-42f1-4e49-2069-faab905d4be2",
  "webapps": [
    {
"name": "Objects",

      "order": 130,
      "fa-icon": "fa-paw",
      "icon": "/main_icons/objects.svg",
      "roles":["admin"],
      "url": "/objects"
    },
    {

      "name": "Scripts",
      "order": 150,
      "fa-icon": "fa-pencil-square-o",
      "icon": "/main_icons/scripteditor.svg",
      "roles":["scripteditor","admin"],
      "url": "/scripteditor"
    }
  ]
}

Modifying the current session

Rebinds the current session to another domain, one of those available for direct switching without authorization. Session work is performed either only by token if the Authorization header is present, or only by cookie. If the token is present but invalid, no work with the cookie occurs.

Request

Example request
PATCH /rest/v1/iam/sessions/current HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "domain": "test.rootdomain.ru"
}

Response

HTTP/1.1 204 No Content
set-cookie: EraSession=07f49a96-0178-a220-2e37-e0d55e0cd303; Expires=Mon, 19 Apr 2021 13:02:24 GMT; Path=/; SameSite=Strict; Secure; HttpOnly

Deleting the current session (logout)

Deletes the current session.

  • If the request contains the Authorization header, an attempt is made to delete the session specified in it, bound to the token. The session bound to the cookie is not affected.

  • If the Authorization header is absent, the session specified in the cookie is deleted.

Request

Example request
DELETE /rest/v1/iam/sessions/current HTTP/1.1

Response

HTTP/1.1 204 No Content
set-cookie: EraSession=deleted; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; SameSite=Strict; Secure; HttpOnly

Deleting the user’s other sessions

Deletes all sessions of the current user except the current one (Authorization header or cookie, as for Deleting the current session (logout)). For an integration channel token session — 400; without a session — 404.

Example request
DELETE /rest/v1/iam/sessions/others HTTP/1.1

HTTP/1.1 204 No Content

See also