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:
| Way | Result |
|---|---|
| A customer signs up in the portal | A new organization with the customer as administrator. See Branding and access. |
stacklane user create on the command line | A new organization and an administrator account. Use --organization to set the name. See Command line. |
stacklane setup | The first organization, with the platform owner as administrator. |
| Import from WHMCS | Organizations 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:
| Role | What the user can do |
|---|---|
administrator | Everything: resources, billing, users, API tokens, the security policy and the audit log. |
engineer | Create and manage resources: instances, SSH keys, projects, hosting services, DNS zones and domain settings. No billing and no users. |
billing | Invoices, payments, credit and the organization details. Can also register domains. |
viewer | Read resources only. |
In detail:
| Action | administrator | engineer | billing | viewer |
|---|---|---|---|---|
| View instances, hosting, domains, DNS zones | Yes | Yes | Yes | Yes |
| Create, change and delete instances, SSH keys, projects | Yes | Yes | No | No |
| Order and cancel hosting, show hosting passwords | Yes | Yes | No | No |
| Add and change DNS zones and records | Yes | Yes | No | No |
| Change nameservers and auto-renew of a domain | Yes | Yes | No | No |
| Register a domain | Yes | No | Yes | No |
| View billing, pay invoices, add credit | Yes | No | Yes | No |
| Change the organization details and VAT number | Yes | No | Yes | No |
| Invite, change and remove users | Yes | No | No | No |
| Create and revoke API tokens | Yes | No | No | No |
| Require two-factor authentication | Yes | No | No | No |
| Read the audit log | Yes | No | No | No |
| Open and answer support requests | Yes | Yes | Yes | Yes |
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.
- Invite. The administrator enters the email address, the name and the role. Stacklane creates the account and sends an invitation with a link to choose a password. The link is valid for 72 hours. An email address can only be used once on the whole platform.
- Change role. An administrator cannot change their own role. The organization must keep at least one administrator. When the role changes, Stacklane revokes the API tokens that the user created.
- Remove. An administrator cannot remove themselves, or the last administrator. Removing a user also revokes the API tokens that the user created.
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.
| Problem | Command |
|---|---|
| The customer forgot the password and cannot use the reset email | sudo -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 codes | sudo -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:
- Create staff accounts in your own organization, not in a customer organization.
- Turn on two-factor authentication for your staff accounts, or require it for your own organization.
- Give each person the lowest staff role they need. Use
supportorbillinginstead ofadminwhere you can. - Remove the staff role with
stacklane user staff --email ... --role nonewhen someone leaves.
Audit log#
Stacklane writes an audit record for sign-ins and for changes to the organization, its users, tokens and resources. Each record contains:
| Field | Meaning |
|---|---|
| Time | When the change happened. |
| Event | The kind of change, for example iam.users.invite or cloud.instances.create. |
| Actor | The user who made the change, with their email address. |
| API token | The token that made the change, when it was made with an API token. |
| Subject | The object that changed, for example instance and its ID. |
| Details | Extra data, for example the old and new role. |
| Source IP and user agent | Where the request came from. |
| Trace ID | The 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:
| Category | Events that start with |
|---|---|
| Authentication | iam.auth |
| Users | iam.users |
| API tokens | iam.tokens |
| Organization | iam.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 parameter | Meaning |
|---|---|
event | Only events that start with this text, up to 64 characters. |
hours | Only events from the last number of hours, from 1 to 8,760. |
limit, offset | Paging. See API. |
The API token needs the administrator role.