Users and Roles

Users

A user in OctoMesh represents an identity that can authenticate and access platform resources. Users are scoped to a tenant — the same person may have separate user accounts in different tenants.

User Properties

Property	Description
UserId	Unique identifier (auto-generated)
Name	Username for login
Email	Email address (unique within tenant)
FirstName / LastName	Optional display name
ExternalLogins	Linked external identity provider accounts
ResetPasswordOnLogin	Forces password change on next login

User Types

Local users authenticate with a username and password stored in the tenant's database.

External users authenticate via an identity provider (Google, Azure AD, LDAP, etc.). On first login through an external provider, OctoMesh creates a local user record linked to the external identity.

Cross-tenant users authenticate through a parent tenant. Their username is prefixed with xt_{parentTenantId}_ to distinguish them from local users. See Cross-Tenant Authentication.

Creating Users

Users can be created in three ways:

1. Via CLI — an administrator creates the user with a password:

   octo-cli -c CreateUser -un "john.doe" -e "john@example.com" -p "SecurePass123"

2. Self-registration — a user signs in via an external identity provider for the first time. The provider must have AllowSelfRegistration enabled (default: true).

3. Admin provisioning — a system administrator pre-provisions a cross-tenant user mapping before the user's first login. See Cross-Tenant Authentication.

Password Management

# Reset a user's password
octo-cli -c ResetPassword -un "john.doe" -p "NewPassword456"

The ResetPasswordOnLogin flag can be set to force users to change their password at next login.

Roles

Roles define permissions in OctoMesh. Services check role claims in the user's access token to authorize operations.

Default Roles

Every new tenant is provisioned with 10 default roles:

Role	Purpose
TenantManagement	Create, configure, and delete tenants
UserManagement	Manage users, roles, groups, and identity providers
CommunicationManagement	Configure communication adapters and pools
Development	Access development features (e.g., GraphQL playground)
AdminPanelManagement	Access and manage the admin panel
BotManagement	Configure and manage scheduled jobs
DashboardManagement	Create and edit dashboards
DashboardViewer	View dashboards (read-only)
ReportingManagement	Create and manage reports
ReportingViewer	View reports (read-only)

Role Assignment

Roles can be assigned to users in two ways:

1. Direct assignment — an administrator explicitly assigns a role to a user:

   octo-cli -c AddUserToRole -un "john.doe" -r "DashboardViewer"

2. Group membership — the user inherits all roles from the groups they belong to. See Groups.

Effective Roles

A user's effective roles are the union of:

• Directly assigned roles
• Roles inherited from all group memberships (including nested groups, up to 10 levels deep)

The Identity Service resolves effective roles at token issuance time and includes them as role claims in the JWT access token.

Managing Roles

# List all roles
octo-cli -c GetRoles

# Create a custom role
octo-cli -c CreateRole -n "DataAnalyst"

# Assign role to user
octo-cli -c AddUserToRole -un "john.doe" -r "DataAnalyst"

# Remove role from user
octo-cli -c RemoveUserFromRole -un "john.doe" -r "DataAnalyst"

# Delete a role
octo-cli -c DeleteRole -n "DataAnalyst"

Access Tokens

When a user authenticates, the Identity Service issues a JWT access token containing:

Claim	Description
sub	User ID
preferred_username	Username
tenant_id	The tenant the user logged into
allowed_tenants	List of tenants the user may access
role	List of effective roles (direct + group-inherited)
home_tenant_id	For cross-tenant users: their home (parent) tenant

Services validate the allowed_tenants claim against the {tenantId} in the request path. Client-credentials tokens (service-to-service, no sub claim) bypass tenant validation.