GET

List Users

Use this API to get a paginated list of users in a OneLogin account.

The list of users can be filtered by a range of user properties including custom attributes. See the Query Parameters section for more detail on the filters that are available.

Syncing Users
When attempting to sync users between OneLogin and another system it is more efficient to use the updated_since query parameter as this will let you return only the users that have changed since the last time you checked.

This call returns up to 50 users per page.

Pagination is implemented using a standard set of querystring variables. Total users, pages and other pagination metadata is available via response headers. For more details see the pagination guide.

Resource URL

https://<subdomain>.onelogin.com/api/2/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

A combination of the following querystring parameters can be used to filter the list of users returned.

Many of the search tools described in our Getting Started documentation can be applied to your parameters, allowing you to fine-tune your results.

created_since

string

An ISO8601 timestamp value that returns all users created after a given date & time. e.g. 2020-07-01T20:38:24Z

created_until

string

An ISO8601 timestamp value that returns all users created before a given date & time.

updated_since

string

An ISO8601 timestamp value that returns all users updated after a given date & time.

updated_until

string

An ISO8601 timestamp value that returns all users updated before a given date & time.

last_login_since

string

An ISO8601 timestamp value that returns all users that logged in after a given date & time.

last_login_until

string

An ISO8601 timestamp value that returns all users that logged in before a given date & time.

firstname

string

The first name of the user

lastname

string

The last name of the user

email

string

The email address of the user

username

string

The username for the user

samaccountname

string

The AD login name for the user

directory_id

string

The ID in OneLogin of the Directory that the user belongs to

external_id

string

An external identifier that has be set on the user

app_id

string

The ID of a OneLogin Application

user_ids

string

A comma separated list of OneLogin User IDs

custom_attributes.{attribute_name}={attribute_value}

string

The short name of a custom attribute. Note that the attribute name is prefixed with custom_attributes. You also have to provide the custom attribute value you're looking for.

fields

string

A comma separated list user attributes to return.

e.g. id,firstname,lastname,profile_picture_url

Sample Responses

200 OK
400 Bad Request
401 Unauthorized
422 Unprocessable Entity

[{
    "activated_at": null,
    "distinguished_name": null,
    "external_id": null,
    "firstname": "Mike",
    "last_login": null,
    "lastname": "Tester",
    "directory_id": null,
    "invitation_sent_at": null,
    "member_of": null,
    "updated_at": "2019-08-22T18:43:55.188Z",
    "created_at": "2019-08-22T18:43:55.188Z",
    "id": 56781966,
    "invalid_login_attempts": 0,
    "locked_until": null,
    "username": null,
    "email": "mike.tester@onelogin.com",
    "phone": null,
    "state": 1,
    "group_id": null,
    "password_changed_at": "2019-08-22T18:43:55.172Z",
    "status": 1,
    "samaccountname": null
  },
  ...
]

With a limited set of fields

[{
      "lastname": "Slater",
      "last_login": "2020-06-03T19:59:21.382Z",
      "id": 36216766,
      "profile_picture_url": null,
      "firstname": "Kelly"
  },
  ...
]

An invalid search parameter was used.

{
    "message": "query parameter(s) not allowed: custom_attributes.date_of_birth",
    "name": "BadRequestError",
    "statusCode": 400
}

{
    "message": "query parameter(s) not allowed: first_login",
    "name": "BadRequestError",
    "statusCode": 400
}

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

{
    "message": "Unauthorized",
    "statusCode": 401,
    "name": "UnauthorizedError"
}

You cant sort on this field.

{
    "message": "Invalid sort field: created_at",
    "field": "created_at",
    "name": "UnprocessableEntityFieldError",
    "statusCode": 422
}

Postman Collection

Sample Code

cURL

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

List Users

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