Configure Access and Permissions in Etlworks

Overview

Etlworks controls access through several independent security layers. Each layer answers a different question, and each is defined and enforced separately. This guide explains every layer, how they combine into an effective decision, and how to configure them for common situations.

IMPORTANT: Some features described in this guide require Etlworks version 9.7.10 or later.

The layers, from broadest to most specific:

The role is always the ceiling. Groups, Permissions, Applications, Tag Views, and tenant restrictions can only narrow what a role allows. Nothing in this guide can raise a user above the authority granted by their role, tenant, license, or environment.

For user identity, roles, and tenant assignment basics, see Users, Roles, and Tenants. This guide is the detailed permission reference that article links to.

Choose the right security model

Start with the simplest model that meets your needs and add layers only when a real requirement appears.

Security layers at a glance

Each layer is defined independently. Do not treat "permissions" as a single umbrella; always name the layer.

Key distinction. Hiding an application in the UI does not block backend access. A user whose Agents application is hidden can still reach Agents through REST, CLI, agentic AI, or MCP unless an operational Permission or a tenant Application restriction also denies it.

Who can manage each layer

How effective access is calculated

An operational Permission decision is resolved in this order. Every step is subject to the ones above it.

1. Hard ceilings. Environment, license, tenant enablement, tenant assignment, tenant Application availability, and tenant AI disablement are checked first. If any of these blocks the action, it is denied regardless of everything below.
2. Role. The role establishes the maximum capability. Nothing below can exceed it.
3. Explicit user Permission. If the user has an explicit Allow or Deny for the domain and action, it applies. A user Deny always denies. A user Allow can create a deliberate exception to a group Deny, but cannot exceed the role or tenant ceiling.
4. Groups. If there is no user override, applicable global and active-tenant groups are combined. A group Deny wins over another group's Allow.
5. Inherit. If no user or group rule decides the action, the role's existing behavior is used unchanged.

An empty Permissions matrix preserves existing role-based behavior. Adding no rows changes nothing.

Use the Effective access report in the User editor to see exactly which rule produced a result.

Configure users and tenant access

Manage users under the Platform area (top-right menu → Users). A user has:

• One role, applied identically in every tenant assigned to the user.
• One or more tenant assignments. Only a Super Admin can add or remove tenant memberships.
• A primary/home tenant (the original assignment) and an optional default tenant (the preferred landing context at login).

Each tenant is an isolated artifact and configuration context. A multi-tenant user works in one active tenant at a time and switches among assigned tenants; switching never combines data across tenants. Group membership, Permissions, and artifact access are evaluated independently in the active tenant.

Expected result. After assigning a second tenant to a non-Super-Admin user, that user sees a Select Tenant option and can switch to the newly assigned tenant, carrying the same role but a separately evaluated policy.

Configure global and tenant user groups

User groups supply reusable, dynamically inherited policy. Manage them under User Groups (Platform area).

Rules that apply to all groups:

• A user can belong to multiple groups.
• Membership is dynamic. Group values are resolved at request time and are never copied into the user.
• Removing a user from a group immediately removes that group's influence.
• Existing individual user settings stay stored and become effective again when group inheritance no longer controls the result.
• A disabled group has no effect.
• A group does not assign a role or a tenant.
• A group cannot contain secrets or credentials.

Inherited through groups: UI application visibility, per-application UI visibility, operational application Permissions, personal OpenAI API-key permission, agentic AI permission, Etlworks API-key authentication permission, and Tag View membership and artifact access rules.

Not inherited through groups: role, tenant assignments, primary or default tenant, account enabled/verified state, password, 2FA secrets, issued Etlworks API keys, the personal OpenAI API-key value, token expiration, AI transcript permission, and tenant quotas/licensing/trial settings.

Configure Applications

Applications control which navigation items and application pages a user sees. Per-user and per-group Application settings are UI-only. Hiding Agents, Flows, or Connections here does not by itself block direct REST, CLI, agentic AI, or MCP access.

Tenant Allowed / Not Allowed Applications are different: they are a tenant-level restriction that acts as an availability ceiling for that tenant and apply beyond simple per-user UI customization.

Expected result. Hiding Metrics for a group removes the Metrics navigation item for members in the UI, but a member with backend View permission for Metrics can still query it through REST or CLI. To block the backend, use a tenant Application restriction or an operational Permission.

Configure operational Permissions

Permissions control operations in each subsystem and are enforced by the backend for the UI, REST API, CLI, agentic AI, and MCP. Actions are:

• View
• Create
• Edit
• Run / Use (Execute)
• Delete

Permissions apply to subsystems including, as applicable: Connections and Formats, Flows, Templates, Schedules, Agents, Explorer, Webhooks, Messages, Metrics/Insights, Audit, Users, Macros, Tags and Tag Views, and Settings/Configuration. Not every action is meaningful for every subsystem.

Set Permissions in the Permissions matrix of the Group editor (saved with the group) or the User editor (an active-tenant override). Each cell uses Inherit, Allow, or Deny. An empty matrix preserves role behavior.

Expected result. Setting Flows → Edit to Deny for a group blocks members from saving changes to any Flow — in the UI and through a direct REST or CLI update — while leaving their role's other Flow abilities intact.

Configure artifact access with Tags and Tag Views

Artifact access controls which specific Flows, Connections, and Formats a user can see and act on. It uses tenant Tag Views as artifact scopes. See Tags and Tag Views for how tags and views are created.

The Artifact access matrix has these columns:

The role remains the maximum permission; artifact rules never elevate a user beyond the role.

Tag View behavior:

• A Tag View contains one or more tags.
• The Tag View editor supports Include and Exclude for users, groups, and roles.
• Explicit exclusions win.
• Administrators bypass Tag View artifact filtering.
• User- and role-only Tag Views preserve their legacy matching behavior.

Closed group scope

Once any of a user's groups is included in an active Tag View for Flow, Connection, or Format access, that group's included Tag Views form an allowlist for that artifact type:

• The user sees only matching artifacts of that type.
• Untagged artifacts are hidden.
• Nonmatching artifacts are hidden.
• Multiple included Tag Views are combined as a union.
• An applicable explicit exclusion still wins.

Example.

• Group: Finance ETL
• Included Tag Views: Finance Production, Finance Shared
• Result: members see Flows, Connections, and Formats matching either included view. They do not see untagged or unrelated artifacts.

No transitive dependency access

Access to a Flow does not automatically grant access to its Connections or Formats. If a user can see a Flow but cannot see one of its referenced Connections or Formats:

• The dependency remains hidden.
• The Flow editor may show an empty or unresolved connection/format selector.
• This is expected behavior, not a rendering defect.
• Administrators should apply a consistent tag taxonomy to the Flow and to every required dependency so that a user who can access a Flow can also access what it references.

Choose artifact permission enforcement mode

Set the environment-wide mode under Settings → Security → Artifact permission enforcement. It has three values:

Important. shadow and off affect only artifact-level operational checks. They do not disable roles, tenant restrictions, tenant Application restrictions, operational subsystem Permissions, user or group UI application visibility, legacy Tag View filtering, or closed group Tag View list filtering. Setting the mode to off does not make all artifacts visible and does not restore hidden Flow dependencies.

Configure Etlworks API-key authentication

An Etlworks API key (also called an Etlworks authentication API key) authenticates a user to Etlworks APIs and the CLI. It is not a personal OpenAI API key — the OpenAI key is a separate AI credential covered in Configure AI access. An Etlworks API key authenticates a user; it does not create a separate authorization identity, and it does not bypass the user's Permissions or artifact access.

API-key authentication policy is resolved across four levels, with the user override applied first, then group, tenant, and environment policy, subject to applicable role behavior:

The user override is tri-state: Use default, Allow, or Disallow. The API User role retains its API-specific behavior.

Environment default. Settings → Security → New users: allow API key authentication:

• Enabled by default for backward compatibility.
• When enabled, new users are created with Use default.
• When disabled, new users are created with an explicit Disallow.
• Existing users are not changed.
• The default applies to users created from the UI, CLI/direct creation, SSO provisioning, and signup paths.

Also applies: global and tenant Max API-key TTL; issue, regenerate, copy, and revoke operations; expired keys no longer authenticate; API-key access can be disabled without deleting the user; and API-key-authenticated requests remain subject to the user's authorization.

Configure AI access

Three AI capabilities are configured independently and are all separate from the Etlworks authentication API key:

• Personal OpenAI API key — a user's own OpenAI credential used to pay for their AI usage. Never confuse this with the Etlworks API key.
• Agentic AI — whether the user can use Simba's agentic actions.
• AI transcript access — whether the user can view AI conversation transcripts.

Environment defaults live under Settings → AI: New users: allow personal OpenAI API key, New users: allow agentic AI, and New users: can view AI transcripts.

• Tenant AI disablement is a hard ceiling — when a tenant disables AI, no AI runs for anyone in it, regardless of user or group settings.
• User and group settings can restrict personal OpenAI keys and agentic AI.
• A group never stores an actual OpenAI key.
• AI transcript access is not inherited from groups. It remains a sensitive capability controlled by the root account owner, who has implicit transcript access.
• Existing users are not retroactively changed by new-user defaults.

Validate access with Effective access

The Effective access section in the User editor is the primary diagnostic tool. For a selected user and tenant it explains:

• Tenant context and role baseline
• Active global and tenant groups
• User overrides
• Application visibility
• Operational permission decisions
• AI and API-key settings
• Artifact scopes
• Enforcement mode
• Policy/diagnostic version

Tenant Administrators do not see sensitive details of global group definitions; global policy is displayed in redacted form.

Expected result. Selecting a user and tenant produces a report naming the exact role, group, and user rule that decided each action, so you can confirm a policy before rollout.

Validate the UI with View as user

View as user lets an administrator experience the product exactly as another user, to validate UI visibility and effective permissions, troubleshoot access reports, and confirm changes before rollout. It never exposes the target's credentials.

• Available to Super Admin and authorized tenant Administrators. A tenant Administrator can view eligible users only in the active tenant.
• A Super Admin target cannot be impersonated. The target must be active and assigned to the selected tenant.
• The session is short-lived, with a default maximum of 30 minutes.
• A persistent banner identifies the impersonated user and provides Exit View as user.
• Every request revalidates administrator authority and target state.
• Actions are audited with both the real administrator and the effective user identities.
• Sessions cannot be nested. API-key-authenticated sessions cannot start impersonation.
• Impersonated sessions cannot be refreshed or tenant-switched.
• Password, account, 2FA, token, and API-key mutations are blocked.
• Exit returns the administrator to their own identity.

API, CLI, agentic AI, and MCP behavior

Authentication method does not bypass authorization. Whether a user acts through the browser UI, the built-in REST APIs, the CLI, the CLI API, agentic AI, or MCP, decisions use the same user, role, tenant context, subsystem Permissions, and artifact policy.

• A user denied Run/Use for Flows cannot run the Flow through CLI or REST.
• A user denied Edit cannot update the Flow through a direct API call.
• A user denied Delete cannot delete it through UI, REST, or CLI.
• A user with the Agents application hidden in the UI can potentially reach Agents through CLI unless an Agents operational Permission or a tenant Application restriction also denies it.
• Search, import/export, recycle-bin restoration, history, logs, dependency discovery, and other secondary endpoints are subject to the relevant subsystem and artifact authorization checks.

API, CLI, AI, and MCP calls must also operate in an authorized tenant context. An API key authenticates a user; it does not create a separate authorization identity. See Authentication API, Calling Etlworks Built-in APIs, and CLI API.

Use-case recipes

Each recipe lists the goal, who configures it, the steps, the effective result, the UI effect, the REST/CLI/AI/MCP effect, common mistakes, and how to validate.

1. Simple single-tenant environment using roles only

• Goal: basic access with no extra layers.
• Who: Administrator.
• Steps: assign each user a role; add no groups, Permissions, or Tag Views.
• Effective result: each user has exactly their role's capability.
• UI effect / channel effect: identical role behavior everywhere.
• Common mistake: adding empty matrices and expecting a change — they preserve role behavior.
• Validate: open Effective access; confirm decisions read "role baseline."

2. Hide unused UI applications without changing API access

• Goal: simplify the UI only.
• Who: Administrator (group) or Super Admin.
• Steps: in a group's Applications, hide the unused items; assign members.
• Effective result: navigation is trimmed; backend authority is unchanged.
• UI effect: hidden items disappear. Channel effect: none — REST/CLI/AI/MCP still work per role/Permissions.
• Common mistake: assuming hiding an application blocks the API. It does not.
• Validate: View as user for the UI; call the API to confirm backend access is unchanged.

3. Allow users to view and run Flows but not edit or delete

• Goal: run-only Flow access.
• Who: Administrator or Super Admin.
• Steps: in a group's Permissions, set Flows → View = Allow, Run/Use = Allow, Edit = Deny, Delete = Deny.
• Effective result: members run Flows but cannot modify or remove them.
• UI effect: edit/delete controls unavailable. Channel effect: edit/delete calls return 403 via REST/CLI.
• Common mistake: expecting a role above the ceiling — a Viewer cannot be granted Run/Use if the role has no execute capability.
• Validate: Effective access shows Edit/Delete = Deny; attempt an API edit and confirm 403.

4. Create a reusable tenant team group

• Goal: shared policy for one team in one tenant.
• Who: Administrator of that tenant, or Super Admin.
• Steps: create a tenant group; set its Applications, Permissions, and Artifact access; add tenant users.
• Effective result: members inherit the group policy in that tenant.
• Common mistake: trying to add users who are not assigned to the tenant — only assigned users are eligible.
• Validate: Effective access lists the tenant group as an active source.

5. Create a global corporate-security group across several tenants

• Goal: one policy applied everywhere.
• Who: Super Admin only.
• Steps: create a global group; set its policy; add members.
• Effective result: policy applies in every tenant where each member is authorized.
• Common mistake: expecting tenant Administrators to see or edit it — global definitions are redacted to them.
• Validate: switch tenants and confirm the global group appears (redacted) in Effective access.

6. Combine a global group with a tenant-specific group

• Goal: corporate baseline plus local specifics.
• Who: Super Admin (global) and Administrator (tenant).
• Steps: add the user to both groups.
• Effective result: policies compose; a Deny in either group wins over the other's Allow.
• Common mistake: assuming the tenant group can loosen a global Deny — it cannot.
• Validate: Effective access shows both sources and the deciding rule.

7. Add an individual exception to a group restriction

• Goal: let one user do something a group denies.
• Who: Super Admin or authorized Administrator.
• Steps: in the User editor Permissions, set the specific action to Allow.
• Effective result: the user Allow overrides the group Deny, but never exceeds the role/tenant ceiling.
• Common mistake: expecting the override to exceed the role — it cannot.
• Validate: Effective access shows "user override: Allow" as the deciding rule.

8. Restrict a team to project artifacts using Tag Views

• Goal: members see only their project's Flows, Connections, Formats.
• Who: Administrator or Super Admin.
• Steps: tag the project artifacts; create a Tag View for those tags; include the team's group in the Tag View.
• Effective result: closed group scope — members see only matching artifacts; untagged and unrelated artifacts are hidden.
• Common mistake: forgetting to tag a required dependency, which then appears blank in the Flow editor.
• Validate: View as user; confirm only tagged artifacts appear.

9. Combine several included Tag Views as a union

• Goal: members see artifacts from two or more views.
• Steps: include the group in multiple Tag Views (for example, Finance Production and Finance Shared).
• Effective result: members see the union of matching artifacts.
• Common mistake: expecting an intersection — included views are unioned.
• Validate: confirm artifacts from both views are visible.

10. Explicitly exclude one user or group from a Tag View

• Goal: remove one subject from an otherwise-included scope.
• Steps: add the user or group to the Tag View's Exclude list.
• Effective result: the explicit exclusion wins even if an include would otherwise match.
• Common mistake: assuming an include elsewhere overrides an exclude — exclusions win.
• Validate: View as user for the excluded subject; confirm the artifacts are hidden.

11. Handle Flows whose Connections or Formats are hidden

• Goal: avoid blank selectors caused by non-transitive access.
• Steps: apply the same tags to a Flow and to every Connection and Format it references.
• Effective result: a user who can access the Flow can also access its dependencies.
• Common mistake: treating the blank selector as a bug rather than a missing dependency tag.
• Validate: View as user; open the Flow and confirm connection/format selectors resolve.

12. Configure a multi-tenant non-Super-Admin user

• Goal: one user working in several tenants.
• Who: Super Admin (only Super Admin manages tenant assignments).
• Steps: assign the user to multiple tenants; optionally set a default tenant.
• Effective result: the user keeps one role across tenants and switches among assigned tenants; policy is evaluated per active tenant.
• Common mistake: believing non-Super-Admin users are limited to one tenant — they are not.
• Validate: log in as the user; confirm Select Tenant lists the assigned tenants.

13. Configure tenant-specific access for the same multi-tenant user

• Goal: different policy per tenant for one user.
• Steps: in each tenant, add the user to that tenant's groups or set active-tenant user Permissions/artifact access.
• Effective result: each tenant evaluates its own groups and overrides independently.
• Common mistake: expecting a tenant override to apply in another tenant — overrides are per active tenant.
• Validate: run Effective access in each tenant context.

14. Configure an API User or service integration

• Goal: an automation identity.
• Who: Administrator or Super Admin.
• Steps: use the API User role (or a suitable role); ensure API-key authentication is allowed; issue an Etlworks API key; confirm the tenant context and backend Permissions.
• Effective result: the integration authenticates and is authorized exactly like the user it represents.
• Common mistake: assuming the API key bypasses Permissions — it does not.
• Validate: call an endpoint the role denies and confirm 403.

15. Disable Etlworks API keys for newly created users

• Goal: new users cannot authenticate with an API key by default.
• Who: Super Admin.
• Steps: Settings → Security → disable New users: allow API key authentication.
• Effective result: users created afterward get an explicit Disallow; existing users are unchanged.
• Common mistake: expecting existing users to change — they do not.
• Validate: create a test user and confirm its API-key override is Disallow.

16. Disable personal OpenAI keys while retaining other AI features

• Goal: block personal OpenAI keys only.
• Steps: restrict the personal OpenAI-key setting on the group or user; leave agentic AI as needed.
• Effective result: members cannot use a personal OpenAI key; other AI features follow their own settings.
• Common mistake: confusing the personal OpenAI key with the Etlworks API key.
• Validate: Effective access shows personal OpenAI key = restricted.

17. Disable agentic AI for selected groups

• Goal: remove agentic AI for some teams.
• Steps: set agentic AI to restricted on the group.
• Effective result: members cannot use agentic actions; question-answering may still work per other settings.
• Common mistake: expecting a group to store an OpenAI key — it never does.
• Validate: View as user; confirm agentic actions are unavailable.

18. Protect AI transcript access

• Goal: limit who can read AI transcripts.
• Who: the root account owner only.
• Steps: grant or revoke transcript access per user; it is not group-inheritable.
• Effective result: only explicitly granted users (and the root owner) can view transcripts.
• Common mistake: trying to grant transcripts through a group — not supported.
• Validate: confirm a non-granted user cannot open transcripts.

19. Roll out artifact permissions with shadow mode

• Goal: validate artifact policy before enforcing.
• Who: Super Admin.
• Steps: set Settings → Security → Artifact permission enforcement to shadow; configure artifact rules; review logs; then switch to enforce.
• Effective result: would-be denials are logged but not blocked until you enforce.
• Common mistake: believing shadow disables other layers — only artifact-level denials are relaxed.
• Validate: confirm logged would-be denials match expectations, then enforce.

20. Temporarily set artifact checks to off

• Goal: isolate whether artifact rules cause an issue.
• Steps: set the mode to off briefly.
• Effective result: artifact-level checks are skipped, but roles, tenant restrictions, subsystem Permissions, UI visibility, and Tag View filtering still apply.
• Common mistake: expecting off to reveal everything or restore hidden Flow dependencies — it does not.
• Validate: confirm the remaining layers still restrict access as designed; return to enforce.

21. Troubleshoot access with Effective access

• Goal: explain why a user can or cannot do something.
• Steps: open the User editor → Effective access; select the tenant; read the deciding rule per action.
• Effective result: the exact role/group/user rule is identified.
• Validate: cross-check the report against the intended policy.

22. Validate the experience with View as user

• Goal: confirm the real UI a user sees.
• Steps: start View as user for the target; review navigation and controls; Exit.
• Effective result: the administrator sees exactly the target's UI and effective permissions.
• Common mistake: attempting to switch tenants or change credentials while impersonating — both are blocked.
• Validate: the banner shows the target; Exit restores the administrator.

23. Diagnose a difference between UI visibility and CLI/API authorization

• Goal: reconcile a UI-hidden item that is reachable by API.
• Steps: confirm the Application is hidden (UI-only); check the subsystem Permission and tenant Application restriction that actually govern the backend.
• Effective result: to block the channel, add an operational Permission Deny or a tenant Application restriction.
• Validate: re-test the API call after adding the backend restriction.

24. Import, export, or restore artifacts when Create/Edit are restricted

• Goal: understand secondary-operation checks.
• Steps: ensure the acting user has View for export, and Create/Edit for the specific artifacts an import or restore would create or change; restore also checks the full missing dependency graph.
• Effective result: imports and restores preflight the real Create/Edit plan and fail closed if any required artifact is not creatable or visible.
• Common mistake: expecting a restore to succeed when a dependent Connection or Format cannot be created.
• Validate: grant the missing Create/Edit or dependency access, then retry.

Troubleshooting

Security design recommendations

• Prefer the simplest model; add layers only for a real requirement.
• Use groups for repeated policy; reserve user overrides for genuine exceptions.
• Enforce operations with Permissions (backend), not Applications (UI-only).
• Apply a consistent tag taxonomy across Flows and their dependencies.
• Roll out artifact policy with shadow, validate with Effective access and View as user, then enforce.
• Keep Etlworks API keys and personal OpenAI keys clearly separated in your own runbooks.
• Restrict AI transcript access to the minimum set of users.

Reference tables and glossary

Role baseline

Security layers and enforcement channels

Super Admin versus Administrator authority

Group scope: global versus tenant

Application visibility versus operational Permissions

Permission values

Artifact visibility values

Artifact enforcement modes

Etlworks API key versus personal OpenAI API key

New-user defaults and existing-user behavior

Effective-decision precedence

Troubleshooting symptom-to-cause

See the Troubleshooting table above for the full symptom-to-cause list.

Glossary

Multi-node behavior

• Security policy is stored durably and shared across nodes.
• Changes publish invalidation to the other nodes.
• Warm authorization checks use a node-local policy cache; they do not query the database on every request.
• Under normal operation, changes propagate promptly.
• If invalidation is interrupted, allow up to approximately 30 seconds for cache convergence before diagnosing a stale permission result.

Backward compatibility

• Existing users, roles, and tenant assignments continue to work.
• No groups and no explicit permission rows means existing role behavior is preserved.
• Existing individual user settings are preserved.
• Existing user/role-only Tag Views preserve legacy behavior.
• Group inclusion in a Tag View introduces the new closed allowlist behavior.
• The new API-key default affects newly created users only.
• enforce is the default artifact permission mode.

See also

• Users, Roles, and Tenants — identity, roles, and tenancy reference.
• Tags and Tag Views — creating tags and Tag Views used for artifact access.
• System Configuration — environment settings.
• Security — platform security overview.
• Authentication API, Calling Etlworks Built-in APIs, and CLI API.