User Import & Export

Auris provides bulk import and export tools for user data. Import users from CSV or JSON files when migrating from another identity provider, onboarding a new department, or seeding a staging environment. Export your user database for backup, compliance audits, or migration to another system.

Access via Console → Settings → Import / Export.

Importing Users

The import flow walks you through file upload, data preview, and processing. Imports run asynchronously — you can navigate away from the page and check progress later.

Import Walkthrough

File Format Requirements

CSV Format

The first row must be a header row with column names. Values containing commas must be quoted. Multi-value fields (like roles) should be quoted and comma-separated within the quotes.

email,firstName,lastName,password,roles
[email protected],Alice,Smith,SecureP@ss123,editor
[email protected],Bob,Jones,AnotherP@ss456,"editor,viewer"
[email protected],Carol,Williams,,viewer

In the example above, Carol has no password — she will need to use Forgot Password or Magic Link to set one.

JSON Format

The file must contain a JSON array of user objects. Each object follows the same field structure as the CSV columns.

[
  {
    "email": "[email protected]",
    "firstName": "Alice",
    "lastName": "Smith",
    "password": "SecureP@ss123",
    "roles": ["editor"]
  },
  {
    "email": "[email protected]",
    "firstName": "Bob",
    "lastName": "Jones",
    "password": "AnotherP@ss456",
    "roles": ["editor", "viewer"]
  },
  {
    "email": "[email protected]",
    "firstName": "Carol",
    "lastName": "Williams",
    "roles": ["viewer"]
  }
]

Import Processing

After clicking Start Import, the import runs asynchronously. Each row is processed sequentially:

1. The email is validated for format and uniqueness
2. If a password is provided, it is hashed with bcrypt
3. The user is created in Prisma (Auris database)
4. The user is created in Keycloak (authentication backend)
5. If roles are specified, the user is assigned to those roles
6. The import progress counter increments

Import History

The Import section shows a history table of all import jobs:

Import Statuses

Viewing Error Details

Click any import with Partial or Failed status to see per-row error details:

Common per-row errors:

Exporting Users

Export your user database to a CSV or JSON file for backup, migration, or compliance purposes.

Export Walkthrough

Exported Fields

The export includes the following fields for each user:

Export History

The Export section shows a history table of all export jobs:

Export files are automatically deleted 24 hours after generation. If you need the file after expiry, run a new export.

API Reference

Import and export operations are also available via the REST API for automation and CI/CD pipelines.

Best Practices

1. Test with a small file first. Before importing 10,000 users, try a file with 5-10 users to verify your column mapping and role names are correct.

2. Pre-create roles. Import does not create roles on-the-fly. Any role names referenced in the import file must already exist in Console → Roles.

3. Use consistent email formatting. Auris treats email addresses as case-insensitive, but the original casing is preserved. Avoid mixing [email protected] and [email protected] in the same file.

4. Schedule large imports during off-peak hours. Each imported user triggers a Keycloak API call. For imports with thousands of users, this generates significant load on Keycloak.

5. Keep export files secure. While exports do not contain passwords, they do contain email addresses, names, and role assignments. Treat export files as sensitive data.

Permissions

Related Guides

• Managing Users — Creating and managing individual users in the Console
• User Import & Export Guide — Detailed developer guide with scripting examples
• Users & Roles — User and role management in the Console
• SCIM Provisioning — Automated provisioning from enterprise IdPs as an alternative to manual import