# Users, settings, and authentication

> Source: https://docs.clonepartner.com/ui/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](/deployment/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:

```bash
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](/api/using-the-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.