Admin Guide

Managing Users

Users are where balance and subscriptions actually live, which makes this the screen where most support work happens.

Last updated 2026-10-13

DigitalKey ERP — Docs · digital-key.co/docs/admin/users

Overview

A user belongs to exactly one tenant, has one role, and carries their own balance and their own feature subscriptions. Two users in the same business are billed entirely separately.

Admin — Users list
Users list
Users list — Users across all tenants with role, lifecycle status, balance, monthly cost and feature count.

Creating a user

POST /api/v1/admin/users
ParameterTypeRequiredDescription
tenant_idintegerRequiredWhich business the user belongs to.
usernamestringRequiredSign-in name. Must be unique across the platform.
passwordstringRequiredInitial password. The user should change it.
full_namestringOptionalDisplay name.
emailstringOptionalEmail address.
phonestringOptionalPhone number.
rolestring= staffRequiredowner or staff.
opening_balancedecimalOptionalBalance to start the account with, in IQD.
WarningSet opening_balance high enough to cover the first month. The first deduction runs the moment the user first signs in — an account created with a zero balance and paid features drops straight into temp_suspend on its very first login.

What the list shows

ParameterTypeRequiredDescription
tenant_namestringOptionalBusiness the user belongs to.
lifecycle_statusstringOptionalregistered, active, temp_suspend, suspend or deactivated.
balancedecimalOptionalCurrent balance in IQD.
monthly_costdecimalOptionalTotal monthly cost of their subscriptions.
billing_dayintegerOptionalDay of the month they are billed.
next_billing_atdateOptionalNext deduction date.
last_billed_atdateOptionalLast successful deduction.
first_login_attimestampOptionalWhen they first signed in.
last_login_attimestampOptionalMost recent sign-in.
feature_countintegerOptionalHow many features they subscribe to.
is_activebooleanOptionalWhether the account is enabled.

Assigning features

  1. 1

    Find the user

    Locate them in the users list.

  2. 2

    Open their features

    The feature panel lists every feature in the catalogue with the ones they already have marked.

    Admin — User features panel
    User features panel
    User features panel — The catalogue with subscribed features checked and prices shown.
  3. 3

    Select what they should have

    Tick to add, untick to remove. Give people what their job needs — a cashier rarely needs finance reporting.

  4. 4

    Save

    The new set applies immediately. Capabilities unlock or lock without the user signing out.

PUT /api/v1/admin/users/{id}/features
ParameterTypeRequiredDescription
feature_idsarrayRequiredThe complete set of feature IDs the user should have. This replaces their current set.
ImportantThe list is a replacement, not an addition. Sending only the feature you want to add removes everything else. Always send the full intended set.
NoteAdding a feature raises the user's monthly cost from their next billing day. It does not take money at the moment of subscribing, so a user can be given a feature before their balance covers it — check the balance against the new monthly total.

Adding balance

POST /api/v1/admin/billing/topup
ParameterTypeRequiredDescription
user_idintegerRequiredWho to credit.
amountdecimalRequiredAmount in IQD.
notesstringOptionalReason or payment reference.
WarningDuplicate top-ups are guarded: the same user and amount within five seconds counts once. A double-click will not double-credit — but two genuine identical top-ups seconds apart will only register one, so leave a gap.
TipA top-up to a suspended user first collects the month that failed, then reactivates them. To restore a suspended customer, credit at least what they owe — a smaller top-up is kept on the balance and the user stays suspended.

Passwords and access

ParameterTypeRequiredDescription
PUT /admin/users/{id}/passwordendpointOptionalSet a new password. Takes new_password.
PUT /admin/users/{id}/toggleendpointOptionalEnable or disable the account.
Importanttoggle is a lifecycle switch, and what it does depends on where the user is. An active user is suspended — blocked at sign-in and on any open session. A suspended or temp-suspended user is reactivated (back to registered if they have never signed in, so billing still starts at first login). A deactivated user goes back to registered. See Lifecycle States.

Related