> For the complete documentation index, see [llms.txt](https://docs.akenza.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akenza.io/general/users.md).

# 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](/general/organization-context.md), as well as one or more [workspaces](/general/workspace-context.md) 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](/general/tenants.md), the akenza deployment they sign in to.

## Registration

A new account is created at [app.akenza.io](https://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:

{% content-ref url="/pages/-MUICYzPAplD8-W7nHt7" %}
[Getting Started](/how-to-create-a-working-environment.md)
{% endcontent-ref %}

Most people never go through this. If you are joining an existing setup, an administrator adds your email address to their [organization](/device-management/managing-an-organization/organization-users.md) or [workspace](/device-management/managing-a-workspace/workspace-users.md) 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.

{% hint style="info" %}
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.
{% endhint %}

## 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.

{% hint style="warning" %}
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.
{% endhint %}

## 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.

{% hint style="danger" %}
An account can only be deleted if it does not own an organization. Transfer ownership to another member in the [organization settings](/device-management/managing-an-organization/general-settings.md) first, then delete the account.
{% endhint %}

## Where access is granted

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

<table><thead><tr><th width="180">Granted at</th><th>Reaches</th><th>Use it for</th></tr></thead><tbody><tr><td><strong>Organization</strong></td><td>The organization and <strong>every</strong> workspace in it, including workspaces created later.</td><td>People who work across the whole account.</td></tr><tr><td><strong>Workspace</strong></td><td>That workspace alone.</td><td>A customer, contractor, or team that should see one project or site only.</td></tr></tbody></table>

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.

{% hint style="info" %}
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.
{% endhint %}

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](/general/tenants.md) 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:

{% content-ref url="/pages/-MVvnykxZJF8KQPqkfwZ" %}
[User Roles](/general/users/user-roles.md)
{% endcontent-ref %}

## Managing users

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-building">:building:</i></td><td><strong>Organization Users</strong></td><td>Add and remove users at organization level, and assign organization roles.</td><td><a href="/device-management/managing-an-organization/organization-users.md">Organization Users</a></td></tr><tr><td><i class="fa-layer-group">:layer-group:</i></td><td><strong>Workspace Users</strong></td><td>Grant access to a single workspace and assign workspace roles.</td><td><a href="/device-management/managing-a-workspace/workspace-users.md">Workspace Users</a></td></tr></tbody></table>

<details>

<summary>Adding users with the API</summary>

Users can also be added through the [REST API](/reference/api-documentation.md), for example to onboard many people at once. Authenticate with an [API key](/device-management/managing-an-organization/api-keys.md) 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](/general/users/user-roles.md).

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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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"}`.

</details>

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akenza.io/general/users.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.