Managing Users

Auris provides a complete user lifecycle management system accessible through both the Admin Console and the REST API. Administrators can list, create, update, disable, soft-delete, and restore users without touching Keycloak’s native admin UI.

Listing Users

The user list supports pagination, full-text search, role filtering, and status filtering. Results are returned in the standard Auris pagination envelope.

Response shape:

{
  "data": [
    {
      "id": "usr_01HX...",
      "email": "[email protected]",
      "username": "alice",
      "firstName": "Alice",
      "lastName": "Rossi",
      "enabled": true,
      "roles": ["member"],
      "createdAt": "2025-03-01T10:00:00Z",
      "lastLogin": "2025-06-10T08:45:00Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Console walkthrough: Navigate to Admin Console → Users. The table refreshes automatically when you change the search term or apply filters. Click any row to open the user detail sheet.

Creating Users

Users can be created directly with a password, or created without one to trigger an invitation email that prompts the user to set their own credentials.

Request body:

{
  "email": "[email protected]",
  "username": "bob",
  "name": "Bob",
  "surname": "Marley",
  "password": "SecurePass123!",
  "sendInvite": false,
  "roles": ["member"],
  "metadata": {
    "department": "engineering",
    "employeeId": "EMP-4421"
  }
}

Field reference:

Console walkthrough: Click the “New User” button on the Users page. The dialog presents a tabbed form: General (name, email), Credentials (password or invite toggle), and Roles (multi-select).

Updating Users

Updatable fields:

{
  "name": "Robert",
  "surname": "Marley",
  "enabled": true,
  "roles": ["member", "billing-admin"],
  "metadata": {
    "department": "leadership"
  }
}

Updating roles replaces the user’s role set entirely — include all intended roles, not just the ones being added. To add a single role without affecting others, read the current role list first, append the new role, then submit the full set.

Updating enabled: false immediately disables the user in Keycloak, invalidating all active sessions.

Soft Delete and Restore

Auris uses soft deletion to preserve audit trails. Deleting a user marks the record with deletedAt rather than removing it from the database or Keycloak.

Restoring a user:

Console walkthrough: The Users page has a “Deleted” filter tab that shows soft-deleted users. Each deleted user row has a “Restore” action in the dropdown menu.

User Sessions

Auris tracks active sessions per user. Administrators can view session details and revoke individual sessions to force re-authentication — useful when a user’s device is lost or compromised.

Session management is handled via the admin sessions endpoint, not per-user routes. Use the userId query parameter to filter sessions for a specific user.

Console walkthrough: Open a user detail sheet and select the “Sessions” tab. Each session shows browser/OS, IP address, login time, and a “Revoke” button.

User Metadata

Metadata allows you to store arbitrary JSON data on a user without modifying the Auris schema. It is returned on every user object and is accessible in the Management SDK.

Common use cases include:

• Application-specific preferences (theme, language, timezone)
• Internal identifiers (employeeId, costCenter, managerId)
• Feature flags or entitlement data
• Onboarding progress tracking

Metadata is stored as a flat or nested JSON object. There is no enforced schema — the structure is entirely application-defined.

{
  "metadata": {
    "department": "engineering",
    "employeeId": "EMP-4421",
    "onboarding": {
      "completed": true,
      "completedAt": "2025-04-15T09:00:00Z"
    }
  }
}

Management SDK

Use the Management SDK for server-side user administration. The Management SDK authenticates via M2M client credentials — it is not intended for use in browser code.

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'https://auth.yourapp.com',
  clientId: process.env.AURIS_CLIENT_ID,
  clientSecret: process.env.AURIS_CLIENT_SECRET,
})
 
// Create a management client authenticated with M2M credentials
const mgmt = auris.createManagementClient({
  clientId: process.env.AURIS_MGMT_CLIENT_ID,
  clientSecret: process.env.AURIS_MGMT_CLIENT_SECRET,
})
 
// List users with pagination
const result = await mgmt.users.list({ page: 1, limit: 20 })
console.log(result.data)       // User[]
console.log(result.pagination) // { page, limit, total, totalPages }
 
// Get a specific user
const user = await mgmt.users.get('usr_01HX...')
 
// Create a user
const newUser = await mgmt.users.create({
  email: '[email protected]',
  firstName: 'Carol',
  roles: ['member'],
  sendInvite: true,
})
 
// Update a user
await mgmt.users.update('usr_01HX...', {
  metadata: { department: 'product' },
})
 
// Disable a user
await mgmt.users.update('usr_01HX...', { enabled: false })
 
// Delete a user (soft)
await mgmt.users.delete('usr_01HX...')

import { createServerManagementClient } from '@auris/nextjs/server'
 
// In a Route Handler or Server Component
export async function GET() {
  // Automatically reads AURIS_MGMT_CLIENT_ID and AURIS_MGMT_CLIENT_SECRET from env
  const mgmt = createServerManagementClient()
 
  const user = await mgmt.users.get('usr_01HX...')
 
  return Response.json(user)
}
 
// Listing users in a Server Component
async function AdminUsersPage() {
  const mgmt = createServerManagementClient()
  const { data: users, pagination } = await mgmt.users.list({
    page: 1,
    limit: 50,
    search: '',
  })
 
  return (
    <ul>
      {users.map((u) => (
        <li key={u.id}>{u.email}</li>
      ))}
    </ul>
  )
}

Required Permissions

Related Pages

• Console: Users & Roles — Visual walkthrough of the Admin Console user management interface
• User Import & Export — Bulk import users from CSV or JSON
• SCIM 2.0 Provisioning — Automated provisioning from Okta, Azure AD, and similar IdPs
• Custom JWT Claims — Inject user metadata into access tokens