Overview

Etlworks supports multi-user and multi-tenant environments. This article is the concise reference for identity and tenancy. For the full permission model — Applications, operational Permissions, artifact access, groups, AI access, and API-key policy — see Configure Access and Permissions in Etlworks.

The building blocks are:

• Users — people and integrations that sign in.
• Roles — each user has one role that sets their baseline and maximum capability.
• Tenant assignments — a user can be assigned to one or more tenants (isolated workspaces). The same role applies in every assigned tenant.
• Primary/home, default, and active tenant — where a user starts and where they are currently working.
• User groups — reusable, dynamically inherited access policy.
• API keys — long-lived credentials for authenticating to Etlworks APIs and the CLI.

Access

Users & Tenants: Top-right menu → Platform → Users or Tenants

• Users: Platform → Users
• User Groups: Platform → User Groups
• Tenants: Platform → Tenants
• Tenant switcher: Top-right menu → ACCOUNT → Select Tenant
• Environment security defaults: Settings → Security (artifact permission enforcement, new-user API-key default, Max API-key TTL)
• Environment AI defaults: Settings → AI (new-user personal OpenAI key, agentic AI, transcript access)

Switch tenant: Top-right menu → ACCOUNT → Select Tenant

Users

Create a user

1. Open Users
2. Click +
3. Enter the required fields and assign a role
4. Assign one or more tenants (Super Admin only)
5. Click Save

An invitation email is sent to the user with a link to complete setup. Expected result: the new user appears in the Users list and can complete setup through the emailed link.

Manage users

The User editor is organized into sections. Most control identity here; the access layers are documented in Configure Access and Permissions in Etlworks.

Section	What it controls
General	Name, email, role, and tenant assignments (Super Admin manages assignments); the home tenant is the user's primary assignment
Applications	Which navigation items the user sees (UI-only)
Groups	Global and tenant group membership
Permissions	Operational View/Create/Edit/Run/Delete per subsystem (backend-enforced)
Artifact access	Tag-View-based access to specific Flows, Connections, Formats
Effective access	Diagnostic report of the final decision for a user and tenant
Security	Etlworks API-key authentication override and key management
AI access	Personal OpenAI key, agentic AI, and transcript settings

From the Users screen you can edit user details, deactivate users, and resend invitations.

Override Security Settings for User

Admins can override some global and tenant security policies for an individual user:

• Allow API key authentication. Controls whether the user's Etlworks API key can authenticate calls to the user-defined and built-in APIs. The override is tri-state: Use default, Allow, or Disallow. It is resolved together with group, tenant, and environment policy. An Etlworks API key authenticates the user; it does not bypass the user's role, Permissions, or artifact access.

Admins and users can generate API keys when allowed by policy.

Notes

• A valid email address is required
• Deactivated users cannot log in

Roles and permissions

Each user is assigned one role that defines their baseline and maximum capability. The same role applies in every tenant assigned to the user. Applications, Permissions, Tag Views, groups, and tenant restrictions can narrow this baseline but never raise it — see Configure Access and Permissions in Etlworks.

Role	Description	Tenant scope
Super Admin	Full system and cross-tenant administration	All tenants (can return to global/root context)
Administrator	Full tenant administration, including users and tenant resources, subject to environment and tenant limits	Assigned tenants
Editor	Resource creation and management similar to Administrator, without user administration and global administrative capabilities	Assigned tenants
Operator	Primarily view and execute access, broader than "run Flows" — can include read/execute areas such as Connections and Explorer	Assigned tenants
Viewer	Read-only access to the applications exposed to the role	Assigned tenants
API User	API-oriented role with limited UI/CLI exposure and access to the user's own API messages; not a general interactive artifact-management role	Assigned tenants

Important

• Only Super Admin has cross-tenant system access and can return to the global/root context.
• Every other role applies identically across all of that user's assigned tenants; a user may be assigned to one or more tenants by a Super Admin.

User groups

User groups supply reusable, dynamically inherited access policy. A global group (managed only by Super Admin) applies in every tenant where the member is authorized; a tenant group applies only in one tenant and can be managed by a Super Admin or an Administrator for that tenant. Group membership is dynamic — removing a user from a group immediately removes its influence, and a group never stores a role, a tenant, or any secret. Full details, including inheritance and the closed Tag View scope, are in Configure global and tenant user groups.

API users and API keys

API User role

Use this role for integrations that call user-defined APIs.

Characteristics:

• Limited UI access: can see only its own API messages
• Interacts only with API endpoints: users with the API User role cannot execute built-in APIs

Users with the Administrator, Editor, and Operator roles can also call user-defined APIs, but API User is the most restricted and secure option.

API key

An Etlworks API key (also called an Etlworks authentication API key) is a long-lived credential that can be used instead of a JWT token when calling Etlworks APIs and the CLI. It is a system-generated, opaque credential and can be non-expiring or time-bound, depending on system configuration.

Do not confuse the Etlworks API key with a personal OpenAI API key. The OpenAI key is a separate AI credential configured under the user's AI settings; it is never used for Etlworks authentication. An Etlworks API key authenticates the user; it does not create a separate authorization identity and does not bypass the user's role, Permissions, or artifact access.

Typical use cases:

• Calling Etlworks APIs and the CLI
• Calling user-defined endpoints (listeners)
• SSO environments with password rotation

Any user can have an API key

• An API key can be generated for a user with any role, including Super Admin.
• API-key authentication is controlled at four levels, resolved with the user override first, then group, tenant, and environment policy:
  • Environment / global setting (Settings → Security)
  • Tenant setting
  • Group setting
  • User override

New-user default. Settings → Security → New users: allow API key authentication is enabled by default. 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.

Manage API key

API keys are managed from the user profile and the User editor Security section.

Create API key

To generate or regenerate an API key, click the generate API key button. When enabled by configuration, the key can be issued with an expiration period in days. If a global or tenant Max API key TTL (days) safeguard is configured, the expiration becomes required and cannot exceed that limit.

Revoke API key

To revoke the API key, click the revoke API key button. Revoking disables API-key access without deleting the user.

Copy API key to the system clipboard

To copy the API key to the clipboard, click the copy API key button.

Show/Hide API key

To toggle between showing and hiding the API key, click the show/hide API key button.

API key notes

• API keys can be non-expiring or time-bound.
• Non-expiring API keys remain valid until revoked.
• Expired API keys can no longer authenticate.
• API keys can be used with any role, subject to system policy.
• API-key authentication can be controlled at the environment, tenant, group, and user levels; the user override is applied first, then group, tenant, and environment policy.
• API-key-authenticated requests remain subject to the user's authorization.

Tenants

Important

• Tenants are available only on dedicated instances.
• Tenants share the same infrastructure but their artifacts are fully isolated.

Tenants overview

Tenants are isolated workspaces within a single Etlworks instance. Each tenant has its own Users, Flows, Connections, Formats, Listeners, Schedules, and Webhooks, and tenant artifacts are fully isolated from each other. A user may be assigned to more than one tenant, but access is always evaluated in one active tenant at a time; switching tenants never combines data.

When to use tenants

• Separate environments (Development, Staging, Production)
• Isolate teams or customers
• Apply different access rules
• Delegate administration

Manage tenants

1. Open Tenants
2. Click + to create a tenant

You can create tenants, edit tenant settings (name, color theme), and deactivate tenants.

Assign users to tenants

• A user can be assigned to one or more tenant workspaces.
• Only a Super Admin can add or remove tenant assignments.
• Assigned tenants determine which workspaces the user can enter; access is evaluated per active tenant.

Change tenant assignments for a user

1. Log in as Super Admin
2. Open Users
3. Select the user and update the Tenants assignment

Primary/home, default, and active tenant

Term	Meaning
Primary/home tenant	The user's original or primary tenant assignment. For a new user, the initial selected tenant becomes the primary/home tenant.
Default tenant	A permitted tenant chosen as the preferred landing context at login; it can determine where the user lands after signing in.
Active tenant	The tenant currently present in the user's session or request context. All access is evaluated here.

Switch tenants

A user assigned to more than one tenant can switch among their assigned tenants without logging out.

1. Open the top-right menu
2. Click Select Tenant
3. Choose a tenant
4. Click Switch

After switching, you operate within that tenant, and group membership, Permissions, and artifact access are evaluated independently in the new active tenant. A Super Admin switched into a tenant is treated as a tenant administrator there, and can return to the global/root context; ordinary multi-tenant users switch only among their assigned tenants. API, CLI, agentic AI, and MCP calls must also operate in an authorized tenant context.

Set default tenant

You can set a default tenant for login. Use this when you work primarily in one tenant and want to avoid switching every time.

Return to the global/root context (Super Admin)

A Super Admin can return to the global/root context:

1. Open Select Tenant
2. Clear the selection
3. Click Switch

Where permissions are configured

Roles set the baseline. Everything that narrows or fine-tunes access — Applications, operational Permissions, artifact access with Tag Views, groups, AI access, API-key policy, enforcement mode, Effective access, and View as user — is documented in Configure Access and Permissions in Etlworks. See also Tags and Tag Views.

SSO user management

Available on dedicated instances. When SSO is enabled:

• Users are matched by email.
• Existing users are logged in.
• New users are created automatically.

New SSO users are assigned to the SSO Landing tenant, given the Viewer role, and created with the environment's new-user security defaults (including the new-user API-key-authentication default). A Super Admin can then assign additional tenants and adjust roles.

Summary

• Users define identity.
• Roles define the baseline and maximum capability, applied across all assigned tenants.
• Tenants define isolation; a user can be assigned to several but works in one active tenant at a time.
• User groups supply reusable policy; API keys enable secure integrations without bypassing authorization.
• Configure the detailed permission layers in Configure Access and Permissions in Etlworks.