Users

What It Is

Users are the accountable identities of a Jetstack tenant. A User record combines identity data, login data, roles, group membership, homepage behavior, timezone preferences, account-validity windows, and several system-managed account-state fields.

In practice, a User is more than a person who can sign in. It is the identity through which the platform evaluates permissions and records responsibility for changes.

Why It Matters

The User model is central to:

  • authentication
  • permissions
  • role-based access
  • group-based organization
  • homepage routing
  • auditability
  • integrations such as REST API and MCP
  • AI-agent execution identities

When a record is created or updated, the acting user identity is reflected in system metadata such as owner and update tracking. This makes user design an operational concern, not just an identity-management concern.

How To Read This Chapter

This chapter follows the actual User configuration surface:

  • identity and login fields
  • access and context fields
  • validity and account-state fields
  • system-managed fields and actions
  • integration design guidance

Use this chapter together with:

Mental Model

Keep these responsibilities separate:

  • the User is the accountable identity
  • Roles define what that identity may do
  • the Group gives the identity organizational context
  • homepage fields affect where the identity lands after sign-in
  • validity and expiration fields determine whether the identity may still operate
  • API keys authenticate as that user and therefore inherit that user’s effective permissions

This is why integrations should usually run under dedicated application users rather than personal accounts.

Configuration Options

avatar

What it is

The profile image of the user.

Why it matters

The avatar improves recognition in administrative listings and identity-related UI surfaces. On the User type it serves as the thumbnail-style visual field.

How to configure it

  • Upload an image in the avatar field.
  • Use a recognizable square or near-square image where possible.

How it behaves

  • It is presentation-oriented. It does not change permissions or authentication.
  • It helps administrators distinguish users quickly, especially in larger tenants.

Example

Use a normal headshot or company avatar for human users. For an application user, use a service icon or system logo so it is immediately obvious that the account is not a human account.

user_name

What it is

The given-name part of the user identity.

Why it matters

It is one of the two editable components that form the computed full_name.

How to configure it

  • Enter the first part of the user’s label in user_name.
  • For human users, use the actual first name.
  • For application users, use the identity prefix you want administrators to see.

How it behaves

  • This field is audited.
  • It feeds the automatically computed display name.

Example

  • Human user: Anna
  • Application user: Application

user_surname

What it is

The surname or second identity segment of the user.

Why it matters

Together with user_name, it forms the displayed full_name.

How to configure it

  • Enter the second part of the user label in user_surname.
  • For human users, use the real surname.
  • For application users, use a descriptive function label.

How it behaves

  • This field is audited.
  • It is not merely cosmetic. It influences how the user is labeled across builder and runtime screens.

Example

  • Human user: Novak
  • Application user: CRM Connector

full_name

What it is

The computed display name of the user.

Why it matters

This is the title-style label used by the platform when it needs to represent the user in pickers, lists, references, and audit-oriented displays.

How to configure it

  • You do not edit full_name directly.
  • Jetstack calculates it from user_name and user_surname.

How it behaves

  • It is expression-driven.
  • It updates when the name parts change.
  • It is the main user label in many screens.

Practical guidance

Because full_name is derived, naming discipline matters. For application users, choose user_name and user_surname so the resulting label is clear in audit history and object metadata.

user_id

What it is

The login identifier of the user, implemented as an e-mail field.

Why it matters

This is the primary sign-in identifier and the address used by account-initiation and password-reset flows.

How to configure it

  • Enter a valid e-mail address in user_id.
  • The field is required when creating and editing the user.
  • The value must be unique.

How it behaves

  • It acts as the main login identity.
  • It is searchable.
  • Duplicate values are rejected.

Best practice

  • Human users should use their real organizational e-mail.
  • Application users should use controlled, non-personal addresses such as application.crm@tenant.example.
  • Do not base long-lived integrations on a personal mailbox that may later disappear or change ownership.

phone

What it is

The phone number of the user.

Why it matters

It enriches the identity profile and may support communication-oriented or challenge-related processes, depending on the tenant design.

How to configure it

  • Enter the user’s phone number in phone.

How it behaves

  • It is searchable.
  • It does not by itself grant or restrict access.

When to use it

  • Use it for human users if phone contact matters operationally.
  • For application users, leave it empty unless there is a specific administrative reason to keep a number here.

password

What it is

The local password credential for the user.

Why it matters

It enables direct password-based authentication where local sign-in is used.

How to configure it

  • Set the password in the password field when creating the user or when deliberately resetting the credential through the user-management flow.
  • Follow the tenant password rules described in Application Settings.

How it behaves

  • It is not exportable as ordinary user data.
  • It is excluded from normal export-style handling.
  • It is not filterable.

Practical guidance

  • For human users, password use is normal unless the tenant relies on a separate identity provider.
  • For application users, routine password-based use should usually be avoided. Prefer API keys or agent-issued tokens where possible.

roles

What it is

The set of roles assigned to the user.

Why it matters

Roles are the main capability and permission layer of the user account.

How to configure it

  • Select one or more roles in the roles field.
  • The field is required.
  • Assign only the roles that are actually needed.

How it behaves

  • The platform evaluates the user through the assigned roles.
  • Role priority affects how some permission decisions are resolved.
  • The same role set is inherited by API and MCP access because those integrations authenticate as the owning user.

Best practice

  • Treat role assignment as the main security decision on the user.
  • Avoid broad convenience roles unless they are really needed.
  • For integrations, create a dedicated role set for the integration account instead of reusing a powerful human administrator account.

user_group

What it is

The Group to which the user belongs.

Why it matters

Group membership provides organizational structure and can influence the user experience, especially around group-level homepage behavior and dashboards.

How to configure it

  • Select a Group in user_group.
  • The field references the Group model directly.

How it behaves

  • The field is upstream-aware and refreshes the form when changed.
  • It uses shorthand-style selection to make picking existing groups easier.
  • It gives the user an organizational home inside the tenant.

Best practice

  • Use business-oriented groups for human users.
  • For integrations, create a dedicated group such as Application access, System integrations, or AI agents.
  • This keeps non-human accounts easy to find and reduces operational confusion.

homepage_module

What it is

The module that should be used as the user’s homepage target.

Why it matters

It affects where the user lands after login when a user-level homepage override is desired.

How to configure it

  • Select a Module in homepage_module.
  • Choose a module that is valid and meaningful for the user’s role.

How it behaves

  • It provides a user-level homepage preference.
  • It is most useful when a specific user should land somewhere different from the default tenant or group behavior.

When to use it

  • Use it for executives, operators, or specialists who need a dedicated landing module.
  • Usually leave it empty for application users, because non-human accounts normally do not need an interactive homepage.

prevent_homepage_module

What it is

A flag that prevents homepage-module behavior for the user.

Why it matters

It lets you explicitly block homepage redirection logic even when a group or other layer would normally supply a homepage.

How to configure it

  • Enable the checkbox when the user should not receive homepage-module routing.
  • Leave it disabled if the user should follow the normal homepage behavior.

How it behaves

  • It acts as a suppression flag.
  • It is useful when a user should behave as an exception to the usual homepage setup.

When to use it

  • Use it when troubleshooting homepage routing.
  • Use it when a service account should never inherit interactive dashboard behavior.

timezone

What it is

The user’s preferred timezone value.

Why it matters

Timezone affects how time-related data should be interpreted for that identity.

How to configure it

  • Enter a valid timezone identifier in timezone.
  • Align it with the actual working timezone of the person or service.

How it behaves

  • It stores user-specific timezone preference.
  • It should be kept consistent with the tenant’s localization strategy.

Best practice

  • Set it deliberately for users who work across regions.
  • For application users, choose the timezone that matches the integration’s operational expectation, or keep the tenant default strategy if no user-specific override is needed.

account_initiation_requested

What it is

The timestamp when account initiation or invite-style setup was requested.

Why it matters

It helps administrators see whether onboarding was started for the account.

How to configure it

  • You do not normally configure this field directly.
  • It is system-managed through account-initiation actions.

How it behaves

  • It is non-editable in normal administration flow.
  • It serves as account-onboarding state information.

account_initiation_completed

What it is

The timestamp when the account-initiation flow was completed.

Why it matters

It distinguishes a merely invited account from one that has finished the initiation process.

How to configure it

  • You do not normally set this manually.
  • It is updated by the relevant account-initiation process.

How it behaves

  • It is system-managed and non-editable.
  • It is useful when diagnosing whether a user ever completed onboarding.

last_login

What it is

The timestamp of the user’s last successful login.

Why it matters

It is one of the most useful operational indicators for account activity.

How to configure it

  • You do not edit last_login directly.
  • The system writes it when the user authenticates successfully.

How it behaves

  • It is non-editable.
  • It helps identify dormant accounts, unused service users, and stale application identities.

Best practice

  • Review this field regularly for application users. If a service identity should be active but has not logged in recently, the integration may be broken.

valid_from

What it is

The start of the account-validity window.

Why it matters

It lets you schedule when a user becomes valid.

How to configure it

  • Set a date and time in valid_from when the account should only become usable after a specific moment.
  • Leave it empty if no delayed start is required.

How it behaves

  • Authentication and key validation respect the user validity window.
  • If the current time is before valid_from, the user is not yet operational.

When to use it

  • Staged onboarding
  • future-dated application cutovers
  • go-live preparation for integrations

valid_to

What it is

The end of the account-validity window.

Why it matters

It lets you set an expiry point for the account.

How to configure it

  • Set a date and time in valid_to when the account should stop being usable.
  • Leave it empty for long-lived accounts that should not expire automatically.

How it behaves

  • Authentication and API-key validation respect this limit.
  • Once the user is beyond valid_to, the account is no longer operational.

Best practice

  • Use it for temporary contractors and temporary service identities.
  • For integrations, this is a good control when testing a time-limited connection or a migration-only application user.

account_expiration_term

What it is

An expiration rule expressed as a date-modifier string used when an account is marked for deletion or termination-oriented handling.

Why it matters

It provides a tenant-controlled way to derive the termination date from a relative term rather than a manually typed absolute end date each time.

How to configure it

  • Enter a supported date-modifier style value in account_expiration_term.
  • Use it only when your account-lifecycle process relies on deferred termination logic.

How it behaves

  • It is an advanced lifecycle field.
  • It is used as a rule, not as a direct permission grant.

Practical guidance

  • Only configure this deliberately and consistently.
  • If your tenant does not use this lifecycle pattern, leave it empty.

login_expired

What it is

A system-style flag indicating that the login is expired or blocked from normal use.

Why it matters

It is part of the account-state layer that can make an account unusable even if roles remain assigned.

How to configure it

  • This is typically controlled through account actions such as blocking or unblocking rather than by casual manual editing.

How it behaves

  • When the platform considers the login expired, the user cannot operate normally.
  • It is an operational state flag, not a role definition.

password_expired

What it is

A flag indicating that the password must be refreshed or is no longer valid for normal use.

Why it matters

It supports credential lifecycle control.

How to configure it

  • This is usually set by the system or by explicit user-management actions, not as an everyday builder configuration field.

How it behaves

  • It affects password-based account usability.
  • It is useful in forced-reset or recovery scenarios.

challenge

What it is

An internal structured field used by the platform for account-challenge related state.

Why it matters

It is part of the system’s internal identity-management machinery.

How to configure it

  • Do not treat this as a normal business configuration field.
  • It is system-managed.

How it behaves

  • It stores serialized structured data.
  • It exists for internal processing rather than end-user administration.

System Metadata And Advanced Fields

The advanced User form also exposes standard system metadata such as object id, creation timestamps, owner, update information, and update actor. These are not ordinary identity fields, but they are important when investigating accountability.

This matters especially for integrations:

  • created objects record the acting user context
  • updates record who changed the object
  • service accounts therefore leave a traceable administrative footprint

Operational User Actions

The User resource also exposes important administrative actions.

Reset password

Use this when a credential must be replaced or recovery should start from a controlled administrative action.

Account initiation or invite

Use this when a new human user should complete onboarding through the formal invitation flow.

Cancel password change request

Use this when a pending password-related request should be invalidated.

Block account and unblock account

Use these actions to make a user temporarily unusable or to restore access without redesigning the user record.

Force logout

Use this when active sessions should be invalidated immediately.

Login as

Use this carefully for support and diagnosis. It is powerful and should remain tightly permissioned.

Generate API key

Use this when a controlled API credential should be issued for another user.

This action matters for integration design because the key authenticates as the selected user identity.

Dedicated Application Users For Integrations

For REST API, MCP, and AI-agent scenarios, it is good practice to create a dedicated non-human User instead of using a personal administrator account.

  • permissions stay explicit and minimal
  • integrations remain stable even when people leave the organization
  • audit history stays understandable
  • operational ownership is easier to review
  • keys and tokens are tied to a controlled identity rather than to a real person

How to configure an application user

  1. Create a normal User record.
  2. Use a descriptive name such as Application CRM Connector or AI Agent Sales Assistant.
  3. Set a controlled integration mailbox in user_id.
  4. Assign only the roles that the integration actually needs.
  5. Put the user into a dedicated Group such as Application access.
  6. Usually leave interactive homepage behavior minimal or disabled.
  7. Generate the API key or agent access token from that user context.

What this means at runtime

  • REST API keys authenticate as the owning user
  • MCP access also runs as the owning user and may additionally be MCP-scoped
  • AI sidecar sessions for tenant agents run under the configured agent user identity
  • created and updated objects record that identity in metadata, which preserves accountability

What to avoid

  • do not use a human administrator’s personal account for permanent integrations
  • do not assign broad roles “just in case”
  • do not hide service accounts among ordinary human groups where they become hard to review

Best Practices

  • Keep human and non-human users clearly separated.
  • Use consistent naming conventions for application users.
  • Review unused or stale users through last_login, valid_to, and role assignment.
  • Keep role assignment minimal and deliberate.
  • Use Groups to make service identities easy to find.
  • Prefer dedicated integration users over shared personal accounts.
Previous← TranslationsNextVersion Management →