User Import & Export

Auris provides a bulk import and export system for user data. Import is useful for migrating from an existing identity provider, onboarding a batch of employees from an HR system, or seeding users in a new tenant. Export is useful for creating backups, auditing your user base, or migrating to another system.

Both operations are asynchronous. Auris processes the file in the background and exposes a job status endpoint so you can poll for completion or display a progress indicator.

Import Formats

Auris accepts two file formats for user import.

CSV Format

The first row must be a header row. Column order does not matter, but column names must match exactly.

email,username,firstName,lastName,password,roles
[email protected],alice,Alice,Rossi,TempPass123!,member
[email protected],bob,Bob,Marley,,member|billing-admin
[email protected],,Carol,White,,,

Column reference:

JSON Format

The file must contain a JSON array of user objects. Fields match the CSV column names.

[
  {
    "email": "[email protected]",
    "username": "alice",
    "firstName": "Alice",
    "lastName": "Rossi",
    "password": "TempPass123!",
    "roles": ["member"]
  },
  {
    "email": "[email protected]",
    "roles": ["member", "billing-admin"]
  }
]

Import Process

curl -X POST https://auth.yourapp.com/api/users/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant: your-tenant" \
  -F "[email protected]"

{
  "ok": true,
  "data": {
    "id": "import_01HX...",
    "fileName": "users.csv",
    "format": "CSV",
    "status": "PENDING",
    "totalRows": 0,
    "processedRows": 0,
    "successCount": 0,
    "errorCount": 0,
    "createdAt": "2025-06-10T14:00:00Z"
  }
}

{
  "ok": true,
  "data": {
    "id": "import_01HX...",
    "status": "PARTIAL",
    "totalRows": 150,
    "processedRows": 150,
    "successCount": 147,
    "errorCount": 3,
    "errors": [
      {
        "row": 12,
        "email": "[email protected]",
        "reason": "Email address already exists in this tenant"
      },
      {
        "row": 67,
        "reason": "Missing required field: email"
      },
      {
        "row": 103,
        "email": "bad-email",
        "reason": "Invalid email address format"
      }
    ]
  }
}

Import Behavior

Understanding how Auris handles edge cases during import:

Duplicate emails: If a user with the same email already exists in the tenant, the row is skipped and counted as an error. The existing user record is not modified.

Missing passwords: Users created without a password are provisioned in a disabled-credentials state. They must use the “Forgot Password” flow or receive an admin-triggered password reset email to gain access.

Role assignment: Roles listed in the import file are assigned after user creation. If a role name does not exist in the tenant, the row is marked as a partial error — the user is created, but the role assignment fails.

Keycloak sync: Each successfully imported user is created in both the Auris database and the underlying Keycloak realm. The two records are linked by keycloakId.

Transaction model: Auris processes rows individually rather than in a single transaction. A failure on row 50 does not roll back rows 1–49.

Listing Import Jobs

Exporting Users

User export generates a file containing all active (non-deleted) users in the tenant. The operation is asynchronous: you trigger the export, then download the file when generation is complete.

Trigger an export

{
  "format": "JSON"
}

Response:

{
  "ok": true,
  "data": {
    "id": "export_01HX...",
    "format": "JSON",
    "status": "PENDING",
    "totalUsers": 0,
    "expiresAt": "2025-06-17T14:00:00Z",
    "createdAt": "2025-06-10T14:00:00Z"
  }
}

Poll for completion

Download the file

curl https://auth.yourapp.com/api/users/export/export_01HX.../download \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant: your-tenant" \
  -o users-export.json

Exported fields

The export includes:

Console Walkthrough

The Console import/export interface is available at Settings → Import/Export.

Importing:

1. Drag and drop a .csv or .json file onto the upload zone, or click to open the file picker.
2. The Console shows a preview of the first 10 rows for validation before submission.
3. After submission, a progress bar tracks processing. The bar updates every few seconds via polling.
4. When the job finishes, a results summary shows success count, error count, and a link to the error details dialog.

Exporting:

1. Select the export format (CSV or JSON).
2. Click “Export Users”. The Console shows the job status.
3. When export is complete, a “Download” button appears. Click it to save the file.
4. Previous exports are listed with their status, creation date, and expiry date.

Required Permissions

Related Pages

• Managing Users — Individual user CRUD via API and Console
• SCIM 2.0 Provisioning — Automated ongoing sync from an external IdP
• Console: Import/Export — Full Console walkthrough with screenshots