Documentation by ClonePartner

Start typing to search.

Using Envoy

Users, roles, and settings

View Markdown

Invite users, assign roles, manage passwords and TOTP, link SSO accounts, and create API keys from the Users and Settings screens.

Users, roles, and settings

The Users screen manages accounts and roles; the Settings screen covers your own account security, linked SSO identities, server status, and API keys. Both are operator screens — server-level authentication options (TOTP enforcement, OAuth providers) are configured in the deployment, not here.

Roles

Envoy has three roles:

  • superadmin — the initial account created during first-time setup. It can manage every non-superadmin user, including admins. The superadmin role cannot be assigned to another user.
  • admin — can create and manage viewer users and can mutate product resources. Only a superadmin can create admins or promote a user to admin.
  • viewer — read-oriented access. Mutation controls (create, edit, delete buttons) are hidden, and the server rejects mutations regardless.

You cannot delete your own account.

Users list

Open Users. The table shows Username, Role, Status, and Created; username, role, and created date are sortable. The toolbar has a Search users... field and a Role filter (Superadmin, Admin, Viewer). The status column shows one of three badges:

  • Invite Pending — the account has an unused, unexpired invite link.
  • Active — the user has completed setup, including TOTP verification.
  • TOTP Pending — the user set a password but has not verified an authenticator code.

Row actions (⋯) are Edit, Regenerate Invite (only while an invite is pending), and Delete.

To invite a user

  1. Open Users and select Add User.
  2. Enter the username and choose a role. Admins can only create viewers; superadmins can create admins or viewers.
  3. Select Create User. The Invite Link Created dialog shows a one-time link.
  4. Copy the link and share it with the user. It can only be used once and expires in 48 hours.

The recipient opens the link, sets a password (at least 8 characters), and — when the server requires TOTP — scans the QR code with an authenticator app and enters the 6-digit code to complete setup. If the link expires, use Regenerate Invite from the user's row actions; regenerating invalidates the old link and resets any partial setup.

To change a role or delete a user

  1. Open the user's ⋯ menu and select Edit.
  2. Change the Role (or set a New Password to reset it) and select Save Changes.
  3. To remove the user, select Delete from the ⋯ menu and confirm. Deletion permanently removes the account and all its sessions.

Settings screen

Open Settings. It contains the following sections; some appear only for admins or depending on server configuration.

Account Security

  • Password — Change Password asks for your current password and a new one of at least 8 characters. Repeated wrong current-password attempts are rate limited.
  • Two-Factor Authentication — shown when the server requires TOTP. Re-enroll TOTP first confirms your current password, then shows a QR code and a Manual Entry Key, and activates after you enter a verification code. Your current TOTP stops working as soon as re-enrollment starts, so keep your authenticator app at hand.

Linked Accounts

Shown when the server has Microsoft or Google OAuth configured. Link starts the provider sign-in flow for your existing Envoy account; once linked, you can sign in with that provider, and Unlink reverts to password-only login. SSO does not create accounts — an administrator invites the user first. Redirect URI setup is covered in Hardening, RBAC, and secrets.

Server Status and Executor Configuration

Read-only panels showing orchestrator health (Status, Active Runs) and how task execution is distributed (Mode, and for HTTP executors the Callback URL and Registered Executors count). Executor mode is configured in the server YAML config and requires a restart to change.

AI Assistant

Admins can store the Anthropic API key used by the in-app AI assistant. The panel shows whether a key is configured and whether it came from Settings or Server config; a key saved here overrides the server YAML, and Clear falls back to the server config when present.

Metrics Backends

Admins can add metrics backends with Add Backend (backend name, JSON config, and an Enabled toggle) and delete them. See Metrics and observability.

API Keys

Admins create bearer keys for programmatic access:

  1. Select Create Key, enter a Name, and optionally an expiry date.
  2. Copy the key from the API Key Created dialog — it is shown only once.

The list shows each key's name, its envoy_ prefix, last-used time, and expiry. The trash action opens Revoke API Key; revoking is permanent and breaks any integration using the key. API Docs opens the deployment's generated endpoint reference; see Using the API for client guidance.