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.
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.
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:
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.
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.
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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
The User resource also exposes important administrative actions.
Use this when a credential must be replaced or recovery should start from a controlled administrative action.
Use this when a new human user should complete onboarding through the formal invitation flow.
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.
Use this when active sessions should be invalidated immediately.
Use this carefully for support and diagnosis. It is powerful and should remain tightly permissioned.
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.
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
- Create a normal User record.
- Use a descriptive name such as
Application CRM Connector or AI Agent Sales Assistant.
- Set a controlled integration mailbox in
user_id.
- Assign only the roles that the integration actually needs.
- Put the user into a dedicated Group such as
Application access.
- Usually leave interactive homepage behavior minimal or disabled.
- Generate the API key or agent access token from that user context.
- 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
- 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
- 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.