See api-docs Menu

Create Session Login Token

Use this API to generate a session login token in scenarios in which MFA may or may not be required. Both scenarios are supported. A session login token expires two minutes after creation.

When MFA is required, this API works in close conjunction with the Verify Factor API call.

For detailed usage flows and examples that illustrate how to use this API to log a user in, see Logging a User in Via API.

Delegated Authentication

You can also use this API to delegate authentication of a user to OneLogin, with or without MFA. Indeed, the Create Session Login Token API returns a session login token, but in cases in which you want to simply authenticate a user in OneLogin, you can just treat the token returned in the 200 OK - Success message as a confirmation that the user has been authenticated.

Likewise, you can use the 401 - Unauthorized status code to indicate that a user could not be authenticated.

As stated above, when MFA is required, the Create Session Login Token API works in close conjunction with the Verify Factor API call. When you want to simply authenticate a user in OneLogin and MFA is required, you can just treat the token returned by the Verify Factor API in the 200 OK - Success message as a confirmation that the user has been authenticated.

Likewise, you can use the 401 - Unauthorized status code to indicate that a user could not be authenticated.

Resource URL

https://api.<us_or_eu>.onelogin.com/api/1/login/auth

Header Parameters

Authorization

required

string

Set to bearer:<access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API can be called using the Authentication Only, Manage Users or Manage All scope.

Content-Type

required

string

Set to application/json.

Custom-Allowed-Origin-Header-1

string

Required for CORS requests only. Set to the Origin URI from which you are allowed to send a request using CORS.

<protocol>://<hostname>:<port>

Port is optional. Do not include path information. Add as many comma-delimited URIs as you like, limited only by header length. You can use additional headers if needed.

For example,

https://www.foo.com,https://doggerel.com:4567

You can use as many headers as you want.

For more information, see Logging a User in Via API and Create Session Via API Token.

Request Parameters

username_or_email

required

string

Set to the username or email of the user that you want to log in.

password

required

string

Set to the password of the user that you want to log in.

subdomain

required

string

Set to the subdomain of the user that you want to log in.

For example, if your OneLogin URL is splinkly.onelogin.com, enter splinkly as the subdomain value.

return_to_url

string

Leave this value blank for now. Intended for future use with multi-factor authentication functionality.

ip_address

string

Leave this value blank for now. Intended for future use with multi-factor authentication functionality. It will be used to set to the IP address of the user accessing your login page.

browser_id

string

Leave this value blank for now. Intended for future use with multi-factor authentication functionality. It will be used to set to the ID of the browser being used by the user to access your login page.

Request Body

{
   "username_or_email":"<username_or_email>",
   "password":"<password>",
   "subdomain":"<subdomain>"
}

Sample Response

This is what a 200 OK response looks like when MFA is not required.

{
    "status": {
        "type": "success",
        "message": "Success",
        "code": 200,
        "error": false
    },
    "data": [
        {
            "status": "Authenticated",
            "user": {
                "username": "kinua",
                "email": "kinua.wong@company.com",
                "firstname": "Kinua",
                "id": 88888888,
                "lastname": "Wong"
            },
            "return_to_url": null,
            "expires_at": "2016/01/07 05:56:21 +0000",
            "session_token": "9x8869x31134x7906x6x54474x21x18xxx90857x"
        }
    ]
}

This is what a 200 OK response looks like when MFA is required.

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "MFA is required for this user",
        "error": false
    },
    "data": [
        {
            "user": {
                "email": "jennifer.hasenfus@onelogin.com",
                "username": "jhasenfus",
                "firstname": "Jennifer",
                "lastname": "Hasenfus",
                "id": 88888888
            },
            "state_token": "xf4330878444597bd3933d4247cc1xxxxxxxxxxx",
            "callback_url": "https://api.us.onelogin.com/api/1/login/verify_factor",
            "devices": [
                {
                    "device_type": "OneLogin OTP SMS",
                    "device_id": 111111
                },
                {
                    "device_type": "Google Authenticator",
                    "device_id": 444444
                }
            ]
        }
    ]
}
{
   "status":{
      "type":"bad request",
      "code":400,
      "message":"MFA is required but the user has not set up any factors",
      "error":true
   },
   "error_method":true
}

{
    "status": {
        "code": 400,
        "error": true,
        "message": "Input JSON is not valid",
        "type": "bad request"
    }
}

Typically, the following error means that your email_or_username and/or subdomain values are invalid.

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "bad request"
    }
}

This error means that your password has expired.

{
    "status": {
        "type": "Unauthorized",
        "message": "Password expired",
        "error": true,
        "code": 401
    }
}

Typically, the following error means that your password is incorrect.

{
    "status": {
    "code": 401,
    "error": true,
    "message": "Authentication Failed: Invalid user credentials",
    "type": "Unauthorized"
}

Typically, the following error means that your access token values are incorrect.

{
    "status": {
    "code": 401,
    "error": true,
    "message": "Authentication Failed",
    "type": "Unauthorized"
}

Typically, the following error means that the access token used to make the call was generated using API credentials that have insufficient permissions. This API can be called using the Manage Users or Manage All scope only.

{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Insufficient Permission"
    }
}

Response Elements

expires_at

Date and time at which the session token will expire. Tokens expire two minutes after creation.

Returned only when MFA is not required.

return_to_url

Returns the return_to_url value sent in the request, if applicable.

Returned only when MFA is not required.

session_token

Provides the session token that can be used to log the user in.

In cases in which you are using this API to simply delegate authentication, you can treat this token as a confirmation that the user has been authenticated.

Returned only when MFA is not required.

status

Authenticated: Indicates that the username_or_email and password values sent in the request are valid.

Returned only when MFA is not required.

user

Provides information about the user that will be logged in via the session token.

  • email
  • firstname
  • id
  • lastname
  • username
state_token

Provides the state_token value that must be submitted with each Verify Factor API call until the session login token has been issued.

Returned only when MFA is required.

callback_url

Provides the Verify Factor API endpoint to which the device_id, state_token, and otp_token must be sent for verification.

Returned only when MFA is required.

devices

Provides device values that must be submitted with the Verify Factor API call.

  • device_type: Lists an available MFA device type, such as OneLogin OTP SMS, Google Authenticator, or Duo Security.

  • device_id: Lists an ID for the device type that must be submitted with the Verify Factor API call.

When the device type is Duo Security, two additional elements are returned:

  • duo_sig_request

  • duo_api_hostname

Returned only when MFA is required

Postman Collection

Be sure to set Postman-specific environment variables indicated by {{ }}.

Download for the Users API

Sample Code

cURL

Replace sample values indicated by < > with your actual values.

curl 'https://api.<us_or_eu>.onelogin.com/api/1/login/auth' \
-X POST \
-H "Authorization: bearer: <access_token>" \
-H "Content-Type: application/json" \
-d '{
    "username_or_email": "<username_or_email>", 
    "password": "<password>", 
    "subdomain": "<subdomain>"
}'

If you are using a CORS request to post the session token, add:


-H "Custom-Allowed-Origin-Header-1: <https://www.foo.com>" \

where https://www.foo.com is the exact URL of the site from which the CORS request will be posted.

Python

See Work with OAuth 2.0 Tokens, Users, and Roles.

Usage Flows and Code Samples

See Logging a User In Via API.


Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.

StackOverflow discussions about "[onelogin] user login api"

  • 2
    Votes
    1
    Answers

    Q: OneLogin session_via_api_token and Chrome

    Asked Nov 14 2016

    I am getting a session token via an ajax call. This in turn calls the API method https://api.us.onelogin.com/api/1/login/auth $.post("onelogin.ashx?action=sessiontoken", data, function (s … is now logged in. session_via_api_token returns response header "Location" with my original page URL. In Chrome the user is not logged in and the response header "Location" is https://app.onelogin.com/login I have a feeling it is a problem with cookies but can't figure out what. Any ideas? …

  • 1
    Votes
    1
    Answers

    Q: Implement custom connector to in-house applications

    Asked Dec 05 2016

    . But I was trying to figure out a way to just navigate the user to the OneLogin login portal and then redirect back to which ever in-house application the user is trying log into. If anyone has any suggestions or an idea on how to best implement this please let me know. … I am trying to figure out how custom connectors work or if it's the correct solution. Basically the company I work at wants to implement a "login using OneLogin" to our in-house applications and we …

  • 1
    Votes
    4
    Answers

    Q: OneLogin Create Session Login Token API returns status 400 with message: Bad Request

    Asked May 23 2016

    Request: //Get the session token for the specified user, using the token recieved from previous web request WebRequest request = WebRequest.Create("https://api.us.onelogin.com/api/1/login/auth … I am developing a C# application which needs to use the onelogin API to retrieve a session token. I am able to authenticate and and create a token with the following code: WebRequest Authrequest …

  • 1
    Votes
    3
    Answers

    Q: onelogin api with php curl 401 unauthorized

    Asked Jul 06 2016

    I have a simple curl request to the onelogin api written in PHP. The request works fine with my parameters from my terminal and I am able to login my user, however the php version I run on server … = "Authorization: bearer: ". $a_token; curl_setopt($ch, CURLOPT_URL, "https://api.us.onelogin.com/api/1/users"); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true …

  • 1
    Votes

    A: Accessing Third Party Apps After Creating A Session Via API Token

    Answered Mar 10 2017

    Two ways: If the app supports SP-initiated SAML, just navigate the user to the application and it'll do the whole SAML flow- App redirects to OneLogin - OL authenticates user (because you have … -for-a-user Take note that you're probably going to want to use the optional flag that makes sure to redirect to your login page, not OL's if you've built a login facade. …

Loading...