Skip to main content

Bulk User Import Reference

This reference describes the bulk user import API. The console has no bulk import control, so you use the API. For the steps, refer to Import Users in Bulk.

Endpoints​

All paths are relative to https://<appliance-address>.

RequestWhat it doesSuccess response
POST /api/users/import?dryRun=trueChecks every row. Adds no one.200, with counts and a results entry for each invalid row.
POST /api/users/importCreates an import job. The job adds the users in the background.202, with the job id and a Location header of /api/users/import/<id>.
GET /api/users/import/<id>Reads the job's status, timestamps, counts, and results.200.

Add createMissingGroups=true to a POST request to create missing groups. A missing group is a group that a row names and the appliance does not have. The default is false.

Sign-In​

Requests to this API use the console session cookie, lp_session. API tokens do not work for these requests.

The sign-in script in Import Users in Bulk gets the cookie from a terminal. It takes the same three steps as the console sign-in.

  1. It starts at /api/auth/login.

  2. It posts your username and password to the sign-in form.

  3. It finishes at /api/auth/callback, which sets the cookie.

The cookie lasts as long as the session. When the session ends, run the script again.

Permissions​

A request without a permission it needs is refused with 403. The message names the missing permission.

RequestPermissions needed
Preview or importusers:create and grants:update
Preview or import with createMissingGroups=trueAlso groups:create
Read a jobusers:read

Row Fields​

The request body is a JSON array of row objects, with one object for each user. The CSV column header gives the column name to use when you convert a CSV file. For the conversion rules, refer to CSV Conversion.

JSON keyCSV columnRequiredValue and rules
emailemailYesTrimmed and lowercased. Must be a valid address of at most 254 characters. A row without an email is invalid. The rest of the file still runs.
firstNamefirst_nameNoTrimmed. At most 255 characters.
lastNamelast_nameNoTrimmed. At most 255 characters.
groupsgroupsNoAn array of group names. If the key is missing or the array is empty, the user joins no groups. A reserved group name is invalid. An unknown group is invalid, unless the request has createMissingGroups=true.
rolesrolesNoAn array of role entries. Each entry is an object with a role and an optional workspace. For the entry rules, refer to Role Entries. A row with no roles adds the user with no workspace access.
statusstatusNoactive (default) or inactive. Any other value is invalid.
passwordpasswordYesUsed exactly as written. Must be 15 to 64 characters, with at least one uppercase letter, one lowercase letter, one digit, and one special character. Set as a temporary password. The user must change it at the first sign-in. A row for a new user without a password is invalid.

The body has these rules:

  • It must be an array of objects, with 1 to 5,000 rows.

  • If a row has a key that is not in the table, the appliance refuses the whole request with 400.

  • groups must be an array of strings, and roles must be an array of objects.

  • A row that fails a row check counts as invalid, with its position. The other rows still run.

Role Entries​

Each entry in roles follows these rules:

  • The role is operator, workspace-admin, or platform-admin. The display names, such as workspace administrator, also work.

  • An operator or workspace-admin entry must name a workspace that exists, such as default-workspace.

  • A platform-admin entry must not name a workspace.

  • A role can appear in more than one entry, each with its own workspace. The user gets one grant for that role over all of those workspaces. A repeated entry adds nothing.

  • An unknown role, an entry with no role, or an entry that breaks a workspace rule makes the whole row invalid.

Row Checks​

The appliance checks each row in this order. The first check that fails is the reason it reports.

  1. The email is present.

  2. The email is a valid address.

  3. The email is at most 254 characters.

  4. The email does not appear in an earlier row of the same file.

  5. The email does not belong to an existing user. If it does, the row is skipped. No later check runs, so the password is not checked.

  6. The first name and the last name are each at most 255 characters.

  7. Each entry in roles names a role that exists on the appliance and follows the workspace rules in Role Entries.

  8. The status is active or inactive.

  9. Each group exists, or the request has createMissingGroups=true. No group is reserved.

  10. The password is present and not empty. If the password is missing or empty, the reason is This box signs people in with a password. Add one to the password column, or use an external identity provider.

  11. The password has no control characters.

When the job adds the user, the identity provider checks the password length and character types. The preview does not run this check. If the identity provider refuses the password, the row counts as failed.

CSV Conversion​

The API accepts JSON only. It does not accept a CSV file. A CSV file must be converted to a JSON array first, with these rules:

  • Each CSV column maps to the JSON key listed in Row Fields.

  • In the groups cell, ; separates the names. Each name becomes one item of the JSON array.

  • In the roles cell, ; separates the entries. An entry is <role>:<workspace>, such as operator:default-workspace. A platform-admin entry is the role name alone. Each entry becomes one object of the JSON roles array.

  • An empty cell means that the key is left out.

  • The password cell is copied exactly and is not trimmed or split. The password needs 15 to 64 characters, with at least one uppercase letter, one lowercase letter, one digit, and one special character. An empty password cell makes the row for a new user invalid.

  • Blank lines are skipped. Row positions in a response count JSON array items, not CSV lines.

In the following example, the CSV file and the JSON array hold the same two users.

users.csv
email,first_name,last_name,groups,roles,status,password
amara@example.com,Amara,Okafor,ml-team,operator:default-workspace,active,ChangeMe-2026!!
kenji@example.com,Kenji,Sato,,operator:default-workspace,active,ChangeMe-2026!!
rows.json
[
{
"email": "amara@example.com",
"firstName": "Amara",
"lastName": "Okafor",
"groups": ["ml-team"],
"roles": [{ "role": "operator", "workspace": "default-workspace" }],
"status": "active",
"password": "ChangeMe-2026!!"
},
{
"email": "kenji@example.com",
"firstName": "Kenji",
"lastName": "Sato",
"roles": [{ "role": "operator", "workspace": "default-workspace" }],
"status": "active",
"password": "ChangeMe-2026!!"
}
]

The ml-team group must exist, or the request must have createMissingGroups=true.

Job Status​

StatusMeaning
PendingThe job waits to start.
RunningThe job is adding users.
CompletedThe job finished.
FailedThe job stopped. statusMessage gives the reason.

Counts​

The preview response and the job both include counts.

CountRows it counts
totalEvery row in the file.
createdRows that add a new user.
skippedRows whose email belongs to an existing user. The existing user is not changed, and the rest of the row is not checked.
invalidRows that fail a row check.
failedRows that passed the checks but that the appliance could not fully add. The results entry gives the reason.
noWorkspaceRows with no roles entries. These users get no workspace access. created also counts these rows.

A skipped row is not a problem. When you import a file again, the appliance skips the users that an earlier import added.

Results​

The results list has one entry for each invalid or failed row.

FieldValue
indexThe row's position in the JSON array, starting at 1.
emailThe row's email.
outcomeinvalid or failed.
detailThe reason.

Access for Imported Users​

  • Each operator or workspace-admin role in a row gives the new user one grant over every workspace that the row names for that role. A platform-admin role gives the user access to the whole appliance.

  • The import creates no API tokens.

Limits​

LimitValue
Rows in one request5,000. A larger file is refused with 422. Split it and send each part.
Request body size32 MiB. A larger body is refused with 413.
Jobs waiting to start10. Another import is refused with 429 until a job finishes.
How long a finished job stays1 hour. After that, reading the job returns 404.
Finished jobs kept100.

Refusals​

A refused request adds no one. Except for 413, the response body is an error object with a code and a message.

StatusWhen
400The body is not an array, is empty, holds an item that is not an object, or uses a key that is not defined.
403A permission is missing. The message names it.
404Reading a job that does not exist, or that finished more than 1 hour ago.
409Another directory owns the user accounts, so the appliance cannot add users.
413The request body is larger than 32 MiB.
422The body holds more than 5,000 rows.
42910 import jobs already wait to start.
503The appliance has no identity provider configured.