Skip to main content

Users, roles and projects

Access in Orchestrate has two layers:

  1. A platform role on the person's account: viewer, developer or admin.
  2. A membership on an organization, a folder or a project, also with the role viewer, developer or admin.

Most actions check the membership. A few platform-wide actions check the platform role.

Add people​

Orchestrate has no self-service sign-up. There are three ways to give someone an account:

  • Invite them. On Identity & SSO > Invitations, enter their email address and, optionally, an organization and role. They get an email, or you send them a one-time link. See Invite people.
  • Connect your identity provider. People then sign in with their existing account, and groups at your provider can give them roles. See Identity and single sign-on.
  • Create them in Keycloak. Users live in the vois-orchestrate realm. Your operator reaches Keycloak's admin console through a port-forward. See Sign in for the first time.

To give someone a platform role, assign viewer, developer or admin to their account in Keycloak, under Role mapping. Roles include each other: admin includes developer, and developer includes viewer.

warning

The install creates a first administrator account. Change its password, or replace it with your own administrator, before anyone else uses the platform. See Install.

Platform roles​

RoleWhat it allows
viewerSign in and see the projects you are a member of.
developerDeploy models, together with a developer or admin membership on the project you deploy into.
adminEverything, in every organization and project. Only a platform admin can add or remove catalog models, restrict them to projects, import model weights, connect clusters, connect identity providers, manage groups, write install-wide custom policies, set budgets and prices, read the audit log and compliance pages, upload the licence and change install settings.

Give the admin role to as few people as you can. A platform admin passes every project check.

On an install that hosts several organizations, there is one more role, the platform operator, and admin means less. See Multi-tenancy.

Organizations, folders and projects​

  • An organization is the top level. A standalone install has exactly one. An install in SaaS mode hosts several, kept apart from each other.
  • Folders group projects inside an organization. They can nest up to 10 levels deep.
  • A project holds agents, workflows, code agents, connectors, knowledge bases, eval suites, channels, phone numbers, voice sessions and Playground sessions. Model deployments can be shared with every project or private to one.

Create folders and projects on the Projects page. You need to be an admin of the organization, or an admin of the folder you create them in.

Membership roles​

You can add a person to an organization, a folder or a project.

MembershipWhat it allows
Project viewerSee the project's agents, connectors, knowledge bases, eval suites, runs and approvals.
Project developerEverything a viewer can, plus create and run agents, build and promote code agents, add connectors and knowledge bases, upload documents, run evals, start voice sessions and calls, approve or reject tool calls, and make an agent version live.
Project adminEverything a developer can, plus manage the project's members, create project and agent keys, switch on hosted chat and channels, choose which agents may call an agent, manage guardrail profiles, set code agent secrets, change agent release settings and override the eval gate.
Folder adminAdmin of every project in the folder and in the folders under it. Can create, delete and restore folders and projects inside it.
Organization adminAdmin of every folder and project in the organization. Can create top-level folders and projects, manage organization members, settings and MFA, invite people, and bind groups to roles in the organization.

A folder or organization membership with the viewer or developer role applies to that level only. Only admin passes down to the folders and projects beneath it.

If an organization requires two-factor sign-in, a member without an authenticator is refused until they set one up.

Add a member​

  1. Open Projects (or Organizations for an organization member).
  2. Select the project or folder.
  3. Under members, search for the person by name or email and pick a Role.
  4. Choose Add.

To remove someone, choose Remove next to their membership. To stop someone signing in at all, disable their account in Keycloak.

Through groups​

Instead of adding people one by one, bind a group to a role on an organization, folder or project, and put people in the group, or let your identity provider fill it. See Groups and roles. Memberships that come from a group are kept apart from the ones you add by hand.

Delete a project​

An organization or folder admin can delete a project from Projects, by typing its id to confirm.

Deleting takes effect at once:

  • the project disappears from every page and every project route, for platform admins too
  • its project keys and agent keys are revoked
  • its channels and hosted chats are switched off

Orchestrate refuses while the project still runs a code agent, a code agent build or a model deployment. Undeploy them first.

A deleted project can be restored from Deleted projects for 7 days by default. Restoring brings the project back, but its keys stay revoked and its channels and chats stay off, so a restore never quietly re-opens a credential. After that period Orchestrate purges it for good: its connector credentials and users' tokens in Vault, its knowledge base data, its code agent sources, and every row of the project. Usage and cost records are kept. A platform admin can purge at once.

API keys and roles​

There are three kinds of key, each for one job:

KeyPrefixBelongs toUsed for
Personal API keyvcpk_The person who created itThe Model Gateway. Never carries the admin role.
Project API keyvcpj_A project, optionally one agentThe Agent API only.
Agent keyvcag_One agent of a projectA code agent's or external agent's Model Gateway calls, and A2A.

The rest of the API, such as managing agents, needs a Keycloak access token. See Call the Model Gateway and API authentication.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →