Clients and users

In Stacklane a client is an organization. Every user belongs to exactly one organization. The organization owns the resources, the invoices, the credit and the API tokens. This page explains how organizations and users are created and managed, how staff accounts fit in, and how the audit log works.

How organizations are created#

An organization is created in one of these ways:

WayResult
A customer signs up in the portalA new organization with the customer as administrator. See Branding and access.
stacklane user create on the command lineA new organization and an administrator account. Use --organization to set the name. See Command line.
stacklane setupThe first organization, with the platform owner as administrator.
Import from WHMCSOrganizations and users from your WHMCS installation. See Migrating from WHMCS.

The back office has no list of all organizations. You see the organization name or ID where it matters: in the helpdesk queue, on invoices, in the list of hosting services and domains, and in the list of DDoS attacks. Customers see their organization ID as Account ID on their dashboard.

Stacklane has no function to sign in as a customer (impersonation).

Roles inside an organization#

Each user has one role inside the organization:

RoleWhat the user can do
administratorEverything: resources, billing, users, API tokens, the security policy and the audit log.
engineerCreate and manage resources: instances, SSH keys, projects, hosting services, DNS zones and domain settings. No billing and no users.
billingInvoices, payments, credit and the organization details. Can also register domains.
viewerRead resources only.

In detail:

Actionadministratorengineerbillingviewer
View instances, hosting, domains, DNS zonesYesYesYesYes
Create, change and delete instances, SSH keys, projectsYesYesNoNo
Order and cancel hosting, show hosting passwordsYesYesNoNo
Add and change DNS zones and recordsYesYesNoNo
Change nameservers and auto-renew of a domainYesYesNoNo
Register a domainYesNoYesNo
View billing, pay invoices, add creditYesNoYesNo
Change the organization details and VAT numberYesNoYesNo
Invite, change and remove usersYesNoNoNo
Create and revoke API tokensYesNoNoNo
Require two-factor authenticationYesNoNoNo
Read the audit logYesNoNoNo
Open and answer support requestsYesYesYesYes

Managing users#

The administrators of an organization manage their own team under Settings → All users. Your staff do not need to do this for them.

A customer administrator cannot change the role of, or remove, a user who has a platform staff role. Only a platform owner or admin can do that.

Help a customer who is locked out#

Run these commands on the server as the service user. See Command line.

ProblemCommand
The customer forgot the password and cannot use the reset emailsudo -u stacklane stacklane user password --email user@example.com sets a new password and signs out all sessions.
The customer lost the two-factor device and the recovery codessudo -u stacklane stacklane user reset-two-factor --email user@example.com removes two-factor authentication and signs out all sessions.

Check the identity of the person before you do this.

Two-factor policy#

An organization administrator can turn on Require two-factor authentication for all users under Settings → General information. Users without two-factor authentication then see a notice and must set it up before they can do anything else. The API answers their requests with 403 and the code two_factor_required. When the policy is on, users cannot turn two-factor authentication off.

Staff accounts#

A staff member is a normal user with a platform staff role. The user still belongs to an organization, often your own company's organization, and has a role in it. See Administration for the staff roles and how to assign them.

Good practice:

Audit log#

Stacklane writes an audit record for sign-ins and for changes to the organization, its users, tokens and resources. Each record contains:

FieldMeaning
TimeWhen the change happened.
EventThe kind of change, for example iam.users.invite or cloud.instances.create.
ActorThe user who made the change, with their email address.
API tokenThe token that made the change, when it was made with an API token.
SubjectThe object that changed, for example instance and its ID.
DetailsExtra data, for example the old and new role.
Source IP and user agentWhere the request came from.
Trace IDThe W3C trace ID of the request. It is also returned in the X-Trace-Id response header.

Where to find it#

Organization administrators see the audit log of their organization under Settings → Audit log. They can filter by category and by period:

CategoryEvents that start with
Authenticationiam.auth
Usersiam.users
API tokensiam.tokens
Organizationiam.clients

The periods are the last 24 hours, 7 days, 30 days and 12 months.

Back-office changes are recorded in the organization of the staff member who made them. Their events start with admin., for example admin.billing.invoices.void. To read them, open the audit log of your own organization with an administrator account.

Sign-in attempts are also recorded: iam.auth.login, iam.auth.login_failed and iam.auth.mfa_failed.

Audit log in the API#

curl 'https://panel.example.com/api/iam/clients/me/audit-logs?event=iam.users&hours=168&limit=50' \
  -H 'Authorization: APIKey 7$<secret>'
Query parameterMeaning
eventOnly events that start with this text, up to 64 characters.
hoursOnly events from the last number of hours, from 1 to 8,760.
limit, offsetPaging. See API.

The API token needs the administrator role.