See api-docs Menu

Create User

Use this API to create a new user in OneLogin.

Early Preview

This API is in early preview and may be subject to change.

Users can be created with a password specified or without one. In the case where a password is not set the user will be created with a status of 7 (Password Pending) and they will not be able to login.

An invite email is not sent when users are created via this API.

Mappings

By default, mappings are run after the response is returned. If you rely on mappings to update a user value and you want that in the response then set the mappings query parameter to sync.

Resource URL

https://<api-domain>/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: Manage Users or Manage All.

Content-Type

required

string

Set to application/json.

Query Parameters

mappings Controls how mappings will be applied to the user on creation.

Defaults to async.

async: Mappings run after the API returns a response
sync: Mappings run before the API returns a response
disabled: Mappings don’t run for this user.

validate_policy Will passwords validate against the User Policy?

Defaults to true.

Request Parameters

You must have either a username, email, or both set as the minimum requirement for creating a user.

username

required

string A username for the user.
email

required

string A valid email for the user.
firstname string The user’s first name.
lastname string The user’s last name.
password string The password to set for a user.
password_confirmation string Required if the password is being set.
password_algorithm string Use this when importing a password that’s already hashed.

salt+sha256 or sha256+salt
Set to the password value using a SHA-256-encoded value.
If you include a salt value in your
request, prepend the salt value to the cleartext password
value before SHA-256-encoding it.

For example, if your salt value is hello and your
cleartext password value is password, the value you
need to SHA-256-encode is hellopassword. The resulting
encoded value would be
9fb8dc1cdabee85d13f5b4ba680a5e71cb8c80e78e5ffe8c01b698fa39346006.

b​crypt

salt string The salt value used with the password_algorithm.
title string The user’s job title.
department string The user’s department.
company string The user’s company.
comment string Free text related to the user.
group_id integer The ID of the Group in OneLogin that the user will be assigned to.
role_ids array A list of OneLogin Role IDs the user will be assigned to.
phone string The E.164 format phone number for a user.
state integer 0: Unapproved
1: Approved
2: Rejected
3: Unlicensed
status integer 0: Unactivated
1: Active
2: Suspended
3: Locked
4: Password expired
5: Awaiting password reset
7: Password Pending
8: Security questions required
directory_id integer The ID of the OneLogin Directory the user will be assigned to.
trusted_idp_id integer The ID of the OneLogin Trusted IDP the user will be assigned to.
manager_ad_id integer The ID of the user’s manager in Active Directory.
manager_user_id integer The OneLogin User ID for the user’s manager.
samaccountname string The user’s Active Directory username.
member_of string The user’s directory membership.
userprincipalname string The principle name of the user.
distinguished_name string The distinguished name of the user.
external_id string The ID of the user in an external directory.

Sample Request Body

Create a user with minimum required fields

{
  "username":"min.requirements"
}

or

{
  "email":"min.requirements@onelogin.com"
}

Create a user with password and custom attribute value.

{
  "firstname":"Happy",
  "lastname":"Gilmore",
  "username":"happy.gilmore",
  "password": "helloworld123",
  "password_confirmation": "helloworld123",
  "custom_attributes": {
    "food": "pizza"
  }
}

Create a user without a password

{
    "email": "chacha@oneloginc.com",
    "department": "Fish Tank Cleaners",
    "company": "Tropical Fish World",
    "username": "chacha",
    "title": "Cleaner",
    "comment": "This is a comment",
    "group_id": 461331,
    "role_ids": [272445],
    "custom_attributes": {
        "employeenumber": "Z88765543",
        "food": "Sushi"
    },
    "invalid_login_attempts": 0,
    "phone": "+1555987654",
    "manager_user_id": null,
    "samaccountname": "chacha.ad",
    "directory_id": null,
    "lastname": "Cha",
    "userprincipalname": "chacha.principle",
    "distinguished_name": "sir.chacha",
    "external_id": "z9876",
    "firstname": "Cha"
}

Sample Response

The full user resource is returned
{
    "created_at": "2020-07-16T03:29:41.420Z",
    "id": 87735981,
    "state": 1,
    "department": null,
    "email": null,
    "last_login": null,
    "password_changed_at": "2020-07-16T03:29:41.377Z",
    "preferred_locale_code": null,
    "firstname": "Scuba",
    "status": 1,
    "userprincipalname": null,
    "title": null,
    "role_ids": [],
    "custom_attributes": {
        "food": null,
        "employeenumber": null
    },
    "lastname": "Steve",
    "updated_at": "2020-07-16T03:29:41.420Z",
    "member_of": null,
    "phone": null,
    "company": null,
    "username": "scuba.steve",
    "manager_ad_id": null,
    "activated_at": null,
    "samaccountname": null,
    "directory_id": null,
    "external_id": null,
    "group_id": null,
    "invalid_login_attempts": 0,
    "invitation_sent_at": null,
    "trusted_idp_id": null,
    "comment": null,
    "distinguished_name": null,
    "locked_until": null,
    "manager_user_id": null
}
{
    "message": "unknown attribute: employee_number",
    "name": "BadRequestError",
    "statusCode": 400
}

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

{
    "message": "Unauthorized",
    "name": "UnauthorizedError",
    "statusCode": 401
}
{
    "message": "Validation failed: Username must be unique within {subdomain}",
    "name": "UnprocessableEntityError",
    "statusCode": 422
}
{
    "message": "Validation failed: Your new password and confirmation password do not match",
    "name": "UnprocessableEntityError",
    "statusCode": 422
}

Postman Collection

Replace sample variables indicated by < > in the sample request body with your actual values. Also, be sure to set Postman-specific environment variables indicated by {{ }}.

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.

curl 'https://<api-domain>/api/2/users' \
-X POST \
-H "Authorization: bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "firstname":"<firstname>",
  "lastname":"<lastname>",
  "email":"<email>",
  "username":"<username>"
}'

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.