GET

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>.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
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

Sample Code

cURL

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

Get Users

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

<h4><span>Get User by Username</span></h4>

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

<h4><span>Get Users Created within Date/Time Range</span></h4>

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

<h4><span>Get Users Assigned to a Specific Role</span></h4>

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

<h3>C#</h3>
<p>See <a href="/api-docs/1/samples/csharp/get-token-and-users">Get Access Token and Users</a>.</p>
<h3>Python</h3>
<p>See <a href="/api-docs/1/samples/python/work-with-tokens-and-users">Work with OAuth 2.0 Tokens, Users, and Roles</a>.</p>