Users, settings, and authentication

Envoy supports local password sessions, optional TOTP, Microsoft Entra ID or Google OAuth, and bearer API keys.

Roles

The built-in roles are:

• Superadmin — the initial account and highest administrative role. It can create or manage admins and viewers.
• Admin — can operate and mutate product resources and manage viewers.
• Viewer — read-oriented access. Mutation controls and write explorer methods are not available.

The superadmin role is created during first-time setup. It cannot be assigned through normal user editing. Admins cannot manage other admins or the superadmin.

Invite a user

From Users:

1. select Add User;
2. enter the username;
3. choose a role available to you;
4. copy the one-time invitation link;
5. deliver it through an approved channel.

The recipient opens the link, sets a password, and enrolls TOTP when required. If an invitation was not completed, a permitted administrator can regenerate it; the earlier token no longer represents the current invitation.

Deleting a user is destructive. Reassign or revoke their automation credentials first.

Password and TOTP

Each local user can change their password from Settings.

When TOTP is required:

• initial setup and invitations include enrollment;
• password login enters a pending state until the code is verified;
• pending sessions cannot call authenticated APIs;
• a user can re-enroll from Settings after confirming the current password.

The QR code is rendered locally in the browser. It is not sent to a third-party QR service.

Re-enrollment replaces the current authenticator secret immediately. Complete it only while the authenticator app is available.

Microsoft and Google sign-in

When an OAuth provider is configured, the login page shows its sign-in action. Envoy uses the Authorization Code flow with PKCE.

OAuth does not create arbitrary product users. An administrator first creates the Envoy account, then that signed-in user links Microsoft or Google from Settings.

If TOTP is also required:

• local password login still requires Envoy TOTP;
• OAuth login delegates MFA to the identity provider and does not add a second Envoy TOTP prompt.

Configure MFA and conditional access at the identity provider before treating SSO as the primary authentication path.

See Server configuration for provider configuration and redirect URI guidance.

API keys

Admins and superadmins can create bearer keys in Settings → API Keys:

1. choose Create Key;
2. enter a purpose-based name;
3. optionally choose an expiry date;
4. copy the key from the one-time reveal.

Use it as:

curl \
  -H "Authorization: Bearer $ENVOY_API_KEY" \
  https://envoy.example.com/api/tasks

The key authenticates as its owner and therefore uses that user's current role. The server stores a hash and only displays a prefix, last-used time, and expiry after creation.

Create and revoke operations themselves require an authenticated browser session; API keys cannot mint more keys. Open API Docs from Settings for the deployment's generated endpoint documentation, and see Using the Envoy API for client guidance.

Revoke a key immediately when a user leaves, a secret may have leaked, or an automation is retired.

Other settings

Depending on role and build, Settings also exposes:

• effective server and runtime information;
• metrics backend configuration;
• AI assistant provider-key configuration.

Secrets entered into these forms are write-only after save. The AI provider key is separate from product API keys.

Access checklist

• Give people the viewer role unless they need mutation access.
• Use named, expiring API keys for each automation.
• Do not share user passwords or API keys.
• Require MFA in Envoy or at the identity provider.
• Remove unused users and revoke their keys.
• Keep a controlled recovery procedure for the superadmin account.