Home >
API >
1 >
Login Pages >
Create Session Login Token

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 without starting a OneLogin session. In delegated authentication, you treat the token returned in the 200 OK - Success message as a confirmation that the user has been authenticated, but you do not use the session token itself.

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

You can perform delegated authentication with or without MFA. 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.

Resource URL

https://<subdomain>/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.

Custom Domains

When a custom domain is in use you still need to provide your original OneLogin subdomain in this field. Do not use the custom domain here.

fields

string

Optional. A comma separated list of user fields to return.

If this attribute is ommited then by default the users id, firstname, lastname, email, and username will be returned.

Otherwise only the list of fields supplied will be returned. For a full list of possible user fields see user resource.

To return custom attributes prefix the field with `custom_attributes`.

{
          "fields": "id, firstname, custom_attributes.employeeNumber"
        }

Request Body

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

Sample Response

200 OK
400 Bad Request
401 Unauthorized

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://subdomain.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"
    }
}

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

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"
}

User account is locked. Usually due to many failed login attempts.

{
    "status": {
        "type": "Unauthorized",
        "code": 401,
        "message": "User is locked. Access is unauthorized",
        "error": true
    }
}

Typically, the following error means that your access token values are incorrect but could also indicate user is suspended or not activated.

{
    "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

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

Sample Code

cURL

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

curl 'https://<subdomain>/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?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

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