Users and roles
Invite people to a tenant, give them roles, organize them in groups and manage their accounts.
People sign in to the Orchestrator with a local account or through your identity provider. An account can belong to several tenants, and in each tenant it has its own roles. This page covers the day-to-day tasks: inviting members, assigning roles, using groups, single sign-on, two-step sign-in, and suspending or removing access.
Who manages what#
| Task | Where | Needs |
|---|---|---|
| Create tenants, manage platform users and identity providers | Platform admin (/admin) |
Platform administrator |
| Invite members, assign roles, manage groups | The tenant's members, roles and groups pages | users.edit, roles.edit (Administrator has both) |
| Grant access to one workspace | The workspace's members | users.edit or folders.edit in that workspace |
| SCIM tokens, external applications | Tenant settings | settings.edit |
| Change your own password, two-step sign-in, passkeys, sessions and tokens | Your profile, Security | Any signed-in user |
For the list of built-in roles and what each allows, see RBAC and permissions.
Invite a member#
Prerequisites:
users.editin the tenant.- Outbound email configured (
VELOPHEX_EMAIL_MODE=Smtp, the default, and a working SMTP host). WithLogmode, the invitation link is written to the API log instead of being mailed. An invitation is valid for 72 hours.
Steps:
- Go to Manage access ▸ Users and select Invite user.
- Enter the person's email address and send the invitation.
- Once they accept, give them roles on the same page, or add them to a workspace from its Settings ▸ Users. See Manage access.
Through the API you can set roles and a workspace in the same call:
HTTPCopyPOST /api/v1/tenants/{tenantId}/invitations
Content-Type: application/json
{ "email": "ana@example.com", "roleIds": ["…"], "workspaceId": "…" }
The invitation token is delivered only by email and never appears in an API response. You can resend or cancel a pending invitation from the same page (POST …/invitations/{invitationId}/resend, DELETE …/invitations/{invitationId}).
Verify: the person follows the link, sets a password and signs in. You should see them listed as a member with the roles you chose, and the Everyone role granted by default.
A default workspace for new members
Set defaultWorkspaceId in the tenant's general settings group to a shared workspace, and every new member joins it with the Automation User role.
Assign or change roles#
- Open the member and choose Roles.
- Add or remove tenant-scoped roles, and workspace-scoped roles per workspace.
- Save.
Changes apply to the member's next request. A personal access token the member created can never exceed the member's current permissions.
To see exactly what someone can do, open their effective access, or call GET /api/v1/tenants/{tenantId}/users/{userId}/effective-access.
Use groups#
Groups save you from assigning the same roles to many people.
- Create a group (for example "Finance automation team").
- Assign roles to the group, at tenant scope or in a workspace.
- Add members.
When someone changes team, move them between groups instead of editing their roles one by one.
Suspend, disable or remove access#
| Action | Effect |
|---|---|
Suspend a member (POST /api/v1/tenants/{tenantId}/members/{userId}/suspend) |
The person loses access to this tenant until reactivated (…/reactivate). Other tenants are unaffected. |
Remove a member (DELETE /api/v1/tenants/{tenantId}/members/{userId}) |
The person leaves this tenant and its role assignments are removed. |
Disable a user account (POST /api/v1/tenants/{tenantId}/users/{userId}/disable) |
The account cannot sign in until enabled again, and its sessions and desktop sign-ins end. |
Send a password reset (POST /api/v1/tenants/{tenantId}/users/{userId}/password-reset) |
The person receives a reset link by email, valid for 30 minutes. |
Reset two-step sign-in (POST /api/v1/tenants/{tenantId}/users/{userId}/mfa/reset) |
Removes the person's authenticator and passkeys, so they can set them up again. Not available for administrator accounts; a platform administrator resets those. |
Losing tenant access also ends the person's Studio and Assistant sign-ins for that tenant at their next token refresh.
When someone leaves
Remove or suspend the member, revoke their personal access tokens, and review Robots or credentials they managed. If they were a tenant administrator with access to secrets, rotate the tenant's data key. See Secrets and encryption.
Sign-in rules#
Password rules, lockout and session length come from the security settings group. The defaults are:
| Setting | Default |
|---|---|
maxFailedLogins |
5 failed sign-ins before lockout |
lockoutMinutes |
15 |
passwordMinLength |
12 (passwords up to 128 characters) |
passwordRequireUpper, passwordRequireLower, passwordRequireDigit, passwordRequireSymbol |
Off |
passwordExpiryDays |
0 (no expiry) |
sessionTimeoutMinutes |
720 (12 hours) |
requireMfa |
Off |
Passwords are hashed with PBKDF2-HMAC-SHA512. The web session is a server-side session held in an HttpOnly, Secure, SameSite=Strict cookie with an absolute lifetime and no sliding expiry.
Each user can review their active sessions under their profile, Security, and sign out other sessions (POST /api/v1/me/sessions/revoke-others).
Two-step sign-in and passkeys#
Local accounts can add a second factor under their profile, Security:
- Two-step sign-in (TOTP). Scan the QR code with an authenticator app (or enter the secret), confirm with a code, and keep the ten single-use recovery codes.
- Passkeys. Add up to ten passkeys or security keys. A passkey works as a second factor, and also on its own through Sign in with a passkey on the sign-in page. Studio and the Assistant sign in through the same browser page, so passkeys work there too.
To require a second factor for everyone, set requireMfa to true in the security group of a tenant (or of the platform). Sign-in is not tenant-specific, so a person who belongs to any tenant that requires it must use it. Someone without a second factor is asked to set one up during sign-in.
Single sign-on and provisioning#
A platform administrator adds identity providers under Platform admin, Identity providers. A provider is platform-wide.
- OpenID Connect, with a preset for Microsoft Entra ID. Register
{your base URL}/api/v1/auth/external/callbackas the redirect URI at the provider. Accounts are linked just in time by a verified email address. Creating an account for an unknown email is off by default and is set per provider; such an account belongs to no tenant until someone adds it. - SAML 2.0 (preview). Not yet checked against a live identity provider; use OpenID Connect for production sign-in. Import the identity provider's metadata by URL or as XML. Signed assertions are always required. Sign-in is started from VeloPhex (SP-initiated); single logout is supported.
Within a tenant, a group can be mapped to a group in your identity provider (the group's Single sign-on setting), so each sign-in adds or removes the person's membership to match.
SCIM 2.0 (preview). Not yet run against Entra ID or Okta provisioning. To provision users and groups from your identity provider, create a SCIM token in the tenant's security settings (settings.edit; shown once) and give your identity provider the tenant URL {your base URL}/scim/v2 and the token. Deactivating a user in the identity provider suspends their tenant membership; deleting removes it. Roles stay with your administrators.
The bootstrap administrator#
The first platform administrator is created at the first start from VELOPHEX_BOOTSTRAP_ADMIN_USERNAME, VELOPHEX_BOOTSTRAP_ADMIN_EMAIL and VELOPHEX_BOOTSTRAP_ADMIN_PASSWORD. After you sign in and change its password, remove those lines from .env and recreate the API container. The bootstrap is ignored once a platform administrator exists.
Next steps#
- Structure access with Workspaces and tenants.
- Tune sign-in rules in Settings.
Who manages what
Invite a member
Assign or change roles
Use groups
Suspend, disable or remove access
Sign-in rules
Two-step sign-in and passkeys
Single sign-on and provisioning
The bootstrap administrator
Next steps