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

# Users and Permissions

Users belong to the Voyzu organization rather than to an individual company. Each user record controls three separate things:

* Who the user is and how they authenticate
* Whether they can use the browser client, the API, or both
* Their role and the companies they can access

Use a separate user for each person or integration. This keeps access revocable and ensures that audit records identify the real actor.

## Signing in

A user has a unique code and may also have a unique email address. A user can sign in to the Voyzu browser client with either identifier:

```
User code + password
Email address + password
```

Codes and email addresses are matched without regard to letter case. Email is optional, so every user should know their user code even when they normally sign in with an email address.

API authentication uses HTTP Basic authentication. The username is the **user code**, not the email address, and the password is the user's Voyzu password.

## UI and API access

Access mode determines how the identity may be used:

| Access mode | Intended use                                     |
| ----------- | ------------------------------------------------ |
| UI          | The user can sign in through the browser client. |
| API         | The user can authenticate API requests.          |
| UI and API  | The same identity can use both channels.         |

Choose API access only when it is required. A separate API-only identity is usually clearer for an integration because its activity can be identified and its credentials can be replaced without affecting a person.

Admin users also have a **Show developer toolbar links** setting. When enabled, Voyzu shows links to developer-facing tools in the application toolbar for that user. Leave it disabled for administrators who do not need development or diagnostic access; it does not grant additional application permissions.

UI passwords must be at least 8 characters. Any identity with API access must use a password of at least 16 characters.

## Passwords and email

Voyzu does not include an email service. Storing an email address allows the user to use it as a login identifier, but Voyzu does not send invitations, passwords, verification messages, or password-reset links.

An administrator must set a password when creating a user and provide it to the user manually through an appropriate secure channel. Administrators can also set a replacement password. A user with UI access can change their own password after signing in.

This also means that an email address is not a recovery mechanism. If a user forgets their password, an administrator must set a new one and communicate it to them outside Voyzu.

## Roles

Roles determine which parts of Voyzu a user can access:

| Role              | Scope                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Admin             | Full application administration, including user management, organization functionality, and access to every active company. |
| Organization user | Organization functionality and access to every active company, without administrator-only settings such as user management. |
| Company user      | Company functionality for explicitly assigned companies only.                                                               |

Admin and organization users do not need individual company assignments. They automatically have access to all active companies, including companies added later. Company assignments apply only to company users.

## Company access

A company user can access only explicitly assigned companies. With no assignments, they have no company available. The company selector and company-level functionality are limited to assigned companies. Assigning another company expands the user's scope without changing their role.

Company access should follow responsibility. For example, a finance team member working for two subsidiaries can be a company user assigned to those two companies, rather than an organization user with access to the entire group.

Deactivating a user prevents further UI and API access without removing the identity or its audit history. Prefer deactivation when access is no longer required so that historical activity remains attributable.

## Practical principles

* Give each person and integration its own identity.
* Use company assignments to keep company users within their responsibilities.
* Reserve organization and admin roles for users who genuinely require access across every company.
* Reserve admin access for application administration.
* Share initial and replacement passwords outside Voyzu using a secure method.
* Deactivate access promptly when a person leaves or an integration is retired.