Arcane.users.add()

This focused page is derived from the mechanically checked full member inventory.

Syntax

Arcane.users.add(usernames)

Parameters

Username or array

Return value

Promise<{users, operation, credentials}>

Description

Creates/configures local Arcane users and returns sensitive temporary credentials for protected presentation.

Overview

Arcane.users.add(usernames) ensures the installation, then creates or configures one or more local standard accounts with the verified Arcane login shell. It requires users.manage, the Provisioner type, elevation, and the exclusive Core mutation boundary. The wrapper accepts one username or an array; the host validates every value and de-duplicates platform-equivalent names.

This is a consequential, non-idempotent account mutation. Existing accounts keep their password while receiving a recoverable shell assignment. A newly created account is staged disabled, with an exact OS identity and prior-shell record, until its returned temporary credential has been delivered and users.activate() succeeds. The host attempts fail-closed rollback after an interruption; recorded partial state must be recovered, not guessed away.

Result, credentials, and events

The exact result is {users, machineUsers, installation, operation, credentials}. users contains per-request native results plus passwordStatus and activationRequired; machineUsers uses the record shape from users.list(). installation is a fresh installation-status object.

For each new account, credentials contains exactly {username, temporaryPassword, mustChangeAtNextSignIn: true, reason: "new-account", activationRequired: true}. Save and present the secret once through protected UI; never log, copy to telemetry, or persist it in ordinary app storage. The standard operation lifecycle events are emitted, and operation.completed.credentials is equally sensitive.

Errors and recovery

Important failures include ADMIN_REQUIRED, OPERATION_BUSY, username and protected-account errors, RELEASE_SECURITY_UNVERIFIED, PARTIAL_ACCOUNT_RECOVERY_REQUIRED, shell backup/change failures, and platform user-provisioning failures. Do not repeat an ambiguous add. Refresh users.list(), preserve any credential already shown, and follow the recorded transaction recovery.

Example

async function addUserAfterValidation(username, confirmAccountChange) {
    const validation = await Arcane.users.validate([username]);
    if (!validation.valid || !confirmAccountChange(validation.users[0])) {
        return null;
    }

    const result = await Arcane.users.add([validation.users[0].username]);
    // Present result.credentials through protected, non-logging UI.
    return result;
}

Reference group

Platform, installation, users, and system