Users

How a user can belong to several organizations and workspaces, holding a different role in each.

A user on akenza represents a person. The same user may be part of one or more organizations, as well as one or more workspaces inside each organization, and may hold a different role in every one of them. Rights are therefore never a property of the person, but of the person in a particular place. Each user belongs to exactly one tenant, the akenza deployment they sign in to.

Registration

A new account is created at app.akenza.io with Register now on the login screen. Registration also asks you to create an organization and a workspace, so that the account has somewhere to work:

Getting Started

Most people never go through this. If you are joining an existing setup, an administrator adds your email address to their organization or workspace instead, and you arrive with access already granted rather than creating an organization of your own.

Signing in

Signing in starts with your email address, after which you continue in one of two ways:

• With the password set on your akenza account.

• With a linked identity provider, so that an account you already have signs you in. Google, Microsoft, and GitHub are supported.

On the Expert and Enterprise tiers, a custom SSO integration with your own identity provider is supported. It is discovered automatically from the domain of the email address you enter, so users at that domain are sent to your identity provider without having to pick anything.

Two-factor authentication

An account can be secured with two-factor authentication using a one-time password (OTP) from an authenticator app. After entering your password you are asked for the current code from that app, so a leaked password is not enough to reach your data on its own.

Set it up under User settings in your user profile with Add 2FA application, then scan the code with your authenticator. More than one authenticator can be registered.

Two-factor authentication is strongly recommended for any real deployment, and especially for accounts holding the organization owner or admin role, since those can change who else has access.

Your user profile

Your profile is reached from the navigation and has two sections:

• User settings holds your account itself: personal information (first and last name, email address, country, and an optional phone number), whether you receive product update and marketing mails, your password, linked identity provider accounts, two-factor authentication, your signed-in devices, and account deletion.

• Access shows which organizations and workspaces you have access to, and the role you hold in each.

Signed in devices lists your active sessions with the device type, IP address, when the session was last used, and when it expires. Any session other than the current one can be signed out from here, which is the thing to reach for if you have used a shared or lost machine.

An account can only be deleted if it does not own an organization. Transfer ownership to another member in the organization settings first, then delete the account.

Where access is granted

Access is granted at one of two levels, and the choice decides how far it reaches:

Granted at	Reaches	Use it for
Organization	The organization and every workspace in it, including workspaces created later.	People who work across the whole account.
Workspace	That workspace alone.	A customer, contractor, or team that should see one project or site only.

The relationship runs in one direction. An organization role above member carries an implicit role in every workspace of that organization. A workspace role never extends up to the organization, nor across to its other workspaces.

A user who has access to at least one workspace appears in the organization's user list as organization member. That role records their presence without granting anything organization-wide, so seeing someone listed there does not mean they were given organization access.

Because organization roles cover workspaces that do not exist yet, granting one is the larger of the two decisions. When in doubt, grant at workspace level and add more later.

Roles

An organization has five roles (owner, admin, editor, viewer, and member) and a workspace has three (admin, editor, and viewer). Broadly, admins manage, editors change things, and viewers read.

Above them, a tenant has two roles of its own, tenant admin and tenant viewer, which span every organization on the deployment.

For exactly what each role may do, down to the individual action, see the permission matrix:

User Roles

Managing users

Organization Users

Add and remove users at organization level, and assign organization roles.

Workspace Users

Grant access to a single workspace and assign workspace roles.

Adding users with the API

Users can also be added through the REST API, for example to onboard many people at once. Authenticate with an API key in the x-api-key header, or with a bearer token in the Authorization header. The caller needs the right to add users at the level it assigns the role, as listed in the permission matrix.

Adding a user is two calls: look up the ID of the role to grant, then assign it to one or more email addresses.

1. Look up the role ID

List the organization roles:

curl --url 'https://api.akenza.io/v3/organization-roles?organizationId=<orgId>' \
  -H 'x-api-key: <apiKey>' \
  -H 'accept: application/json'

Or the roles of a workspace:

curl --url 'https://api.akenza.io/v3/workspace-roles?organizationId=<orgId>&workspaceId=<wsId>' \
  -H 'x-api-key: <apiKey>' \
  -H 'accept: application/json'

The response is a page of roles. Each carries its id, name, description, and the permissions it grants per resource:

{
  "content": [
    {
      "id": "6000000000000003",
      "name": "Organization-Admin",
      "description": "Organization Admins can manage and edit the Organization and have full access on its Workspaces.",
      "permissions": {
        "asset": ["*"],
        "organization": ["read", "update", "manage"],
        "organization.member": ["*"],
        "workspace": ["*"],
        "workspace.member": ["*"]
      }
    }
  ],
  "totalElements": 3
}

2. Assign the role

At organization level:

curl --url 'https://api.akenza.io/v3/organization-roles/assign?organizationId=<orgId>' \
  -H 'x-api-key: <apiKey>' \
  -H 'content-type: application/json' \
  --data-raw '{"members":[{"email":"<userEmail>","roleId":"<roleId>"}],"sendNotifications":true}'

At workspace level:

curl --url 'https://api.akenza.io/v3/workspace-roles/assign?organizationId=<orgId>&workspaceId=<wsId>' \
  -H 'x-api-key: <apiKey>' \
  -H 'content-type: application/json' \
  --data-raw '{"members":[{"email":"<userEmail>","roleId":"<roleId>"}],"sendNotifications":true}'

members takes several entries, so one call can add a whole team, each with its own role. With sendNotifications set to true, every user added receives an email about their new access. A successful call answers with a confirmation such as {"message":"Organization roles successfully assigned"}.

Usage example

Generally, users are intended to represent people within your own organization or your customers' organizations.

A facility manager who only ever looks at one building belongs in that building's workspace. A platform administrator who maintains device types and dashboards for every site belongs at organization level, because that work spans all of them.