Users, roles and projects
Access in Orchestrate has two layers:
- A platform role on the person's account: viewer, developer or admin.
- 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-orchestraterealm. 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.
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
| Role | What it allows |
|---|---|
viewer | Sign in and see the projects you are a member of. |
developer | Deploy models, together with a developer or admin membership on the project you deploy into. |
admin | Everything, 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.
| Membership | What it allows |
|---|---|
Project viewer | See the project's agents, connectors, knowledge bases, eval suites, runs and approvals. |
Project developer | Everything 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 admin | Everything 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 admin | Admin of every project in the folder and in the folders under it. Can create, delete and restore folders and projects inside it. |
Organization admin | Admin 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
- Open Projects (or Organizations for an organization member).
- Select the project or folder.
- Under members, search for the person by name or email and pick a Role.
- 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:
| Key | Prefix | Belongs to | Used for |
|---|---|---|---|
| Personal API key | vcpk_ | The person who created it | The Model Gateway. Never carries the admin role. |
| Project API key | vcpj_ | A project, optionally one agent | The Agent API only. |
| Agent key | vcag_ | One agent of a project | A 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.