See api-docs Menu
  1. Home >
  2. API >
  3. 1 >
  4. Users >
  5. Get Users

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

Before calling this API, consider using its version /2 equivalent.

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

  • lastname

  • id

  • manager_ad_id

  • role_id

  • samaccountname

  • since

  • until

  • username

  • userprincipalname

  • custom_attributes.{attribute_name}

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://<subdomain>.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://<subdomain>.onelogin.com/api/1/users?email=katinka*

    https://<subdomain>.onelogin.com/api/1/users?email=*@onelogin.com

  • Return a limited number of users:

    https://<subdomain>.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://<subdomain>.onelogin.com/api/1/users?sort=+id

  • Return users displaying only selected fields per user:

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

  • Return users based on custom attribute value:

    https://<subdomain>.onelogin.com/api/1/users?custom_attributes.employeeNumber=123456

    Also supports wildcard search

    https://<subdomain>.onelogin.com/api/1/users?custom_attributes.fav_color=re*

  • Combine use of multiple query parameters using an &:

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

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
{
   "status":{
      "error":false,
      "code":200,
      "type":"success",
      "message":"Success"
   },
   "pagination":{
      "before_cursor":null,
      "after_cursor":"xxxxb3VudF9pZDo6Oi0tIyNpZDo6OjY3NzI0NzQ",
      "previous_link":null,
      "next_link":"https://subdomain.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,
         "manager_user_id": 29260307,
         "role_id": [
           77777,
           111111
         ],
         "company": "OneLogin",
         "department": "Finance",
         "title": "Captain",
         "state": 1,
         "trusted_idp_id": null,
         "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,
         "manager_user_id": 29260307,
         "role_id": null,
         "company": "",
         "department": "",
         "title": "",
         "state": 1,
         "trusted_idp_id": null,
         "custom_attributes": {
           "alias": "",
           "branch": ""
         }
      }
   ]
}

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

Run In Postman

    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.

Get Users

curl 'https://<subdomain>/api/1/users' \
-X GET \
-H "Authorization: bearer:<access_token>"

Get User by Username

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

Get Users Created within Date/Time Range

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

Get Users Assigned to a Specific Role

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

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.