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>.
| Request | What it does | Success response |
|---|---|---|
POST /api/users/import?dryRun=true | Checks every row. Adds no one. | 200, with counts and a results entry for each invalid row. |
POST /api/users/import | Creates 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.
-
It starts at
/api/auth/login. -
It posts your username and password to the sign-in form.
-
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.
| Request | Permissions needed |
|---|---|
| Preview or import | users:create and grants:update |
Preview or import with createMissingGroups=true | Also groups:create |
| Read a job | users: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 key | CSV column | Required | Value and rules |
|---|---|---|---|
email | email | Yes | Trimmed 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. |
firstName | first_name | No | Trimmed. At most 255 characters. |
lastName | last_name | No | Trimmed. At most 255 characters. |
groups | groups | No | An 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. |
roles | roles | No | An 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. |
status | status | No | active (default) or inactive. Any other value is invalid. |
password | password | Yes | Used 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. -
groupsmust be an array of strings, androlesmust 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, orplatform-admin. The display names, such asworkspace administrator, also work. -
An
operatororworkspace-adminentry must name a workspace that exists, such asdefault-workspace. -
A
platform-adminentry 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.
-
The email is present.
-
The email is a valid address.
-
The email is at most 254 characters.
-
The email does not appear in an earlier row of the same file.
-
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.
-
The first name and the last name are each at most 255 characters.
-
Each entry in
rolesnames a role that exists on the appliance and follows the workspace rules in Role Entries. -
The status is
activeorinactive. -
Each group exists, or the request has
createMissingGroups=true. No group is reserved. -
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. -
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
groupscell,;separates the names. Each name becomes one item of the JSON array. -
In the
rolescell,;separates the entries. An entry is<role>:<workspace>, such asoperator:default-workspace. Aplatform-adminentry is the role name alone. Each entry becomes one object of the JSONrolesarray. -
An empty cell means that the key is left out.
-
The
passwordcell 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 emptypasswordcell 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.
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!!
[
{
"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
| Status | Meaning |
|---|---|
Pending | The job waits to start. |
Running | The job is adding users. |
Completed | The job finished. |
Failed | The job stopped. statusMessage gives the reason. |
Counts
The preview response and the job both include counts.
| Count | Rows it counts |
|---|---|
total | Every row in the file. |
created | Rows that add a new user. |
skipped | Rows whose email belongs to an existing user. The existing user is not changed, and the rest of the row is not checked. |
invalid | Rows that fail a row check. |
failed | Rows that passed the checks but that the appliance could not fully add. The results entry gives the reason. |
noWorkspace | Rows 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.
| Field | Value |
|---|---|
index | The row's position in the JSON array, starting at 1. |
email | The row's email. |
outcome | invalid or failed. |
detail | The reason. |
Access for Imported Users
-
Each
operatororworkspace-adminrole in a row gives the new user one grant over every workspace that the row names for that role. Aplatform-adminrole gives the user access to the whole appliance. -
The import creates no API tokens.
Limits
| Limit | Value |
|---|---|
| Rows in one request | 5,000. A larger file is refused with 422. Split it and send each part. |
| Request body size | 32 MiB. A larger body is refused with 413. |
| Jobs waiting to start | 10. Another import is refused with 429 until a job finishes. |
| How long a finished job stays | 1 hour. After that, reading the job returns 404. |
| Finished jobs kept | 100. |
Refusals
A refused request adds no one. Except for 413, the response body is an error object with a code and a message.
| Status | When |
|---|---|
400 | The body is not an array, is empty, holds an item that is not an object, or uses a key that is not defined. |
403 | A permission is missing. The message names it. |
404 | Reading a job that does not exist, or that finished more than 1 hour ago. |
409 | Another directory owns the user accounts, so the appliance cannot add users. |
413 | The request body is larger than 32 MiB. |
422 | The body holds more than 5,000 rows. |
429 | 10 import jobs already wait to start. |
503 | The appliance has no identity provider configured. |