See api-docs Menu

Get Users

This call returns up to 50 users per page.

For details about using the pagination element to easily “page” through users, see Pagination.

For details about each element in the User resource, see User Resource.

Resource URL

https://api.<us_or_eu>.onelogin.com/api/1/users

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 any one of the following scopes: Read Users, Manage users, Read All, or Manage All.

Query Parameters

  • directory_id

  • email

  • external_id

  • firstname

  • id

  • manager_ad_id

  • role_id

  • samaccountname

  • since

  • until

  • username

  • userprincipalname

The following examples illustrate how to use various query parameters to return subsets of users:

  • Return the user whose email value equals hazel.zhang@onelogin.com

    https://api.us.onelogin.com/api/1/users?email=hazel.zhang@onelogin.com

  • Include wildcards. For example, you can return all users whose email values start with Katinka or all users whose email values end with @onelogin.com:

    https://api.us.onelogin.com/api/1/users?email=katinka*

    https://api.us.onelogin.com/api/1/users?email=*@onelogin.com

  • Return a limited number of users:

    https://api.us.onelogin.com/api/1/users?limit=10

  • Return users sorted by id. Use + to sort in ascending order or - to sort in descending order:

    https://api.us.onelogin.com/api/1/users?sort=+id

  • Return users displaying only selected fields per user:

    https://api.us.onelogin.com/api/1/users?fields=email, username, status

  • Combine use of multiple query parameters using an &:

    https://api.us.onelogin.com/api/1/users?role_id=111111&sort=+id&fields=email, username

  • Return users created within a window of time bound by specific created_at values using the since and until parameters:

    https://api.us.onelogin.com/api/1/users?since=2010-11-01T19:44:55.681Z&until= 2011-11-01T19:44:55.681Z

    This will return users created after 2010-11-01T19:44:55.681Z, but before 2011-11-01T19:44:55.681Z.

For more details, see Using Query Parameters.

Sample Responses

{
   "status":{
      "error":false,
      "code":200,
      "type":"success",
      "message":"Success"
   },
   "pagination":{
      "before_cursor":null,
      "after_cursor":"xxxxb3VudF9pZDo6Oi0tIyNpZDo6OjY3NzI0NzQ",
      "previous_link":null,
      "next_link":"https://api.us.onelogin.com/api/1/users?after_cursor=
                   xxxxb3VudF9pZDo6Oi0tIyNpZDo6OjY3NzI0NzQ"
   },
   "data":[
      {
         "activated_at":"2009-05-05T00:00:00.000Z",
         "created_at":"2009-05-05T03:18:08.338Z",
         "email":"hazel.zhang@onelogin.com",
         "username":"hzhang",
         "firstname":"Hazel",
         "group_id":123456,
         "id":1,
         "invalid_login_attempts":0,
         "invitation_sent_at":"2011-09-20T16:14:48.344Z",
         "last_login":"2009-12-08T23:02:36.786Z",
         "lastname":"Zhang",
         "locked_until":null,
         "notes":null,
         "openid_name":"hazel.zhang",
         "locale_code":null,
         "password_changed_at":"2013-12-02T00:00:00.000Z",
         "phone":"",
         "status":1,
         "updated_at":"2015-08-21T23:12:08.495Z",
         "distinguished_name":null,
         "external_id":null,
         "directory_id":null,
         "member_of":null,
         "samaccountname":null,
         "userprincipalname":null,
         "manager_ad_id":null,
         "role_id": [
           77777,
           111111
         ],
         "custom_attributes": {
           "alias": "Haz",
           "branch": "Southwest Center"
         }
      },
      ...
      {
         "activated_at":"2011-07-26T19:50:47.242Z",
         "created_at":"2009-08-05T20:59:20.190Z",
         "email":"amaya@onelogin.com",
         "username":"",
         "firstname":"Amaya",
         "group_id":123456,
         "id":2,
         "invalid_login_attempts":0,
         "invitation_sent_at":"2011-08-10T14:22:16.466Z",
         "last_login":"2015-10-08T02:59:33.732Z",
         "lastname":"Gomez",
         "locked_until":null,
         "notes":null,
         "openid_name":"amaya.gomez",
         "locale_code":null,
         "password_changed_at":"2015-09-09T16:11:09.542Z",
         "phone":"650-555-1212",
         "status":1,
         "updated_at":"2015-10-08T02:59:33.982Z",
         "distinguished_name":null,
         "external_id":null,
         "directory_id":null,
         "member_of":null,
         "samaccountname":"amaya.gomez",
         "userprincipalname":null,
         "manager_ad_id":null,
         "role_id": null
      }
   ]
}

Typically, this error means that your Authorization header value is missing or incorrectly formatted. The Authorization header value should use this format: bearer:<access_token>.

{
   "status":{
      "error":true,
      "code":400,
      "type":"bad request",
      "message":"Authorization Information is incorrect"
   }
}

Typically, this error means that your access token value is invalid.

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

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

Download for the Users API

Sample Code

cURL

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

Get Users

curl 'https://api.<us_or_eu>>.onelogin.com/api/1/users' \
-X GET \
-H "Authorization: bearer:<access_token>"

Get User by Username

curl 'https://api.<us_or_eu>>.onelogin.com/api/1/users?username=<username>' \
-X GET \
-H "Authorization: bearer:<access_token>"

Get Users Created within Date/Time Range

curl 'https://api.<us_or_eu>>.onelogin.com/api/1/users?since=<since>&until=<until>' \
-X GET \
-H "Authorization: bearer:<access_token>"

Get Users Assigned to a Specific Role

curl 'https://api.<us_or_eu>>.onelogin.com/api/1/users?role_id=<role_id>' \
-X GET \
-H "Authorization: bearer:<access_token>"

C#

See Get Access Token and Users.

Python

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


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.