Roles and permissions

Access to the service is controlled by roles. Every user signs in with the identity of your organization. Roles assigned to the user decide which agents, datasources and administrative functions they can use.

Two kinds of roles

Kind	Defined by	Controls
Service roles	The service	Administrative functions, such as managing agents or datasources
Access roles	You	Who may use a specific agent or search a specific datasource

Service roles

Role	Allows	Typical holders
service-operator	Create and change components, environments, secrets, guardrails, policies and deployments. Create, change and delete datasources.	Developers and operators who build agents
service-monitoring	Call the health endpoint of all agents	Monitoring systems
service-feedback	Read and manage the feedback of all users, not only their own	People who evaluate agent quality

Access roles

For agents

Each deployment lists the roles that may use its agents in access_control.execute_roles. A user needs at least one of these roles. The roles are created automatically when the deployment is saved.

{ "access_control": { "execute_roles": ["support-tier-1", "support-tier-2"] } }

For datasources

Each datasource lists the roles that may search it and load documents into it in access_control.execute_roles. A user needs at least one of these roles.

Caution

A datasource without execute_roles can be used by every signed-in user of your tenant. Always set roles for datasources with restricted content.

Assign roles to users

On request, your tenant administrators receive limited administrative access to the identity management of your tenant. With it, they can manage users and groups and assign roles themselves. Contact Support to request access or if you do not know who your tenant administrator is.

Use groups

Assign roles to groups, not to individual users. A user then gets all roles of the groups they belong to.

flowchart LR
    U1[Anna] --> G1[Group: plant-a-maintenance]
    U2[Ben] --> G1
    U3[Chris] --> G2[Group: agent-developers]
    G1 --> R1[Role: maintenance-agent-users]
    G1 --> R2[Role: maintenance-manuals]
    G2 --> R3[Role: service-operator]

Benefits:

• Onboarding and offboarding take one step: add the user to a group, or remove them.
• Access is easy to review: the groups show who can use which agents and datasources.
• Changes apply to everyone at once: give a group a new role, and all members can use the new agent.

Recommendations:

• Model groups on your organization, for example teams, plants or functions: plant-a-maintenance, quality-engineering.
• Name roles after what they allow, for example maintenance-agent-users or maintenance-manuals. Use lowercase letters and dashes.
• Reuse roles across deployments and datasources that belong to the same user group.
• Keep administrative roles in separate groups, for example agent-developers for service-operator, and keep these groups small.
• Give each group the minimum roles it needs.
• Use separate roles for test and production if different people should have access.
• Review group memberships regularly, for example every quarter.

Errors

Status	Meaning
401	The token is missing, invalid or expired
403	The user does not have a required role, or X-Tenant-ID does not match the token

Tenant isolation

Each customer is a separate tenant. Agents, datasources, secrets and conversations of one tenant are never visible to another tenant. Every request carries the tenant in the token and in the X-Tenant-ID header, and both must match.