Login

Login
Log in and start an authenticated session

Authenticates a user against Installer and starts a session. This is the entry point for all other Installer APIs - every subsequent request must present the credentials returned here.

How to use the response:

  • On success, the Set-Cookie response header contains the session cookie and the X-XSRF-TOKEN response header contains the XSRF token. Send the cookie value in the Cookie request header and the token value in the X-XSRF-TOKEN request header on every subsequent request.
  • The roles returned in the response body determine which of the other Installer APIs this user is authorized to call (see the security requirements on each operation).

Notes:

  • If the user's password has expired, the API returns 302 and redirects to the change-password flow instead of returning 200. Call POST /iam/change-password before retrying login.
Request
URI
POST
https://{api_host}/sspi/iam/login
COPY
Request Body
LoginRequest of type(s) application/json
Required  

Show optional properties

{
    "user_name": "string",
    "password": "string",
    "user_type": "string"
}
{
    "user_name": "admin",
    "password": "********",
    "user_type": "LOCAL_USER"
}
string
user_name
Required  

The user name to authenticate. For LDAP users, this may need to include the domain, depending on how the identity source is configured.

string
password
Required  

The password for user_name. Not returned in any response.

string
user_type
Required  

Identifies whether an identity is a local Installer account, a remote user authenticated through a configured LDAP identity source, or a remote LDAP group.

Enumeration: LOCAL_USER, REMOTE_USER, REMOTE_GROUP
Responses
200

Login succeeded. The session cookie and XSRF token are returned in the response headers.

Returns LoginAuthResponse of type(s) application/json 
{
    "user_name": "admin",
    "display_name": "Administrator",
    "user_type": "LOCAL_USER",
    "roles": [
        {
            "role": "ENTERPRISE_ADMIN",
            "display_name": "Enterprise Admin"
        }
    ]
}
string
user_name
Optional

The user name that was authenticated.

string
display_name
Optional

The human-readable name for this user, suitable for showing in a UI.

string
user_type
Optional

Identifies whether an identity is a local Installer account, a remote user authenticated through a configured LDAP identity source, or a remote LDAP group.

Enumeration: LOCAL_USER, REMOTE_USER, REMOTE_GROUP
array of object
roles
Optional

The roles held by this user, which determine which Installer APIs the current session is authorized to call.

Response Headers

string
Set-Cookie

Session cookie. Send it back in the `Cookie` header of subsequent requests.

string
X-XSRF-Token

XSRF token. Send it back in the `X-XSRF-TOKEN` header of subsequent requests.


302

The user's password has expired. Redirects to the change-password flow instead of completing login.

Operation doesn't return any data structure

Response Headers

string
Location

URL of the change-password page to redirect the user to.


400

The request body is malformed or missing a required field.

Returns Error of type(s) application/json 
{
    "error_code": 0,
    "module_name": "string",
    "error_message": "string"
}
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


401

The user name, password, or user type is incorrect.

Returns Error of type(s) application/json 
{
    "error_code": 0,
    "module_name": "string",
    "error_message": "string"
}
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


403

Forbidden

Returns Forbidden of type(s) application/json 
{
    "error_code": 0,
    "module_name": "string",
    "error_message": "string"
}
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


412

Precondition Failed

Returns PreconditionFailed of type(s) application/json 
{
    "error_code": 0,
    "module_name": "string",
    "error_message": "string"
}
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


428

Precondition Required

Returns PreconditionRequired of type(s) application/json 
{
    "error_code": 0,
    "module_name": "string",
    "error_message": "string"
}
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


429

Too Many Requests

Returns TooManyRequests of type(s) application/json 
{
    "error_code": 0,
    "module_name": "string",
    "error_message": "string"
}
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


500

Internal server error

Returns Error of type(s) application/json 
"Error Object"
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


default

4XX and 5XX type errors with appropriate message

Returns Error of type(s) application/json 
"Error Object"
integer
error_code
Required  

HTTP Status or Application error code.

string
module_name
Optional

Module where the error happened.

string
error_message
Required  

Message describing the error.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"user_name":"string","password":"string","user_type":"string"}' https://{api_host}/sspi/iam/login
On This Page
User Management Operations
POST
Login
POST
Logout
POST
Change Password
POST
Reset Password
GET
Get Current User Info
GET
Get All Users Info
GET
Get All Roles Info
GET
Get All Role Bindings
POST
Bind Roles To Entity
GET
Get Role Binding
PUT
Update Roles To Entity
DELETE
Delete Roles To Entity
GET
Get All Ldap Identity Sources
POST
Create Ldap Identity Source
GET
Get Ldap Identity Source
PUT
Update Ldap Identity Source
DELETE
Delete Ldap Identity Source
GET
Search Ldap Identity Source