Digital Employee Access Control

By default, every enabled Digital Employee is available to all users who have chat access. Access control lets you restrict each agent to specific users or groups — for example, only HR staff can interact with the HR Agent, and only the IT team can reach the IT Support Agent.

Admin-only feature

Only admins can configure access. Users can only interact with agents they have been granted access to.

---

How It Works

Access control for Digital Employees uses the same access grants system as Knowledge Bases, Models, and other workspace resources:

• Each grant specifies a principal (a user or group) and a permission (read)
• An empty grants list means all users with chat access can use the agent
• Once grants are added, only the listed users and groups can see and interact with the agent

Grants are stored in the agent's config and applied immediately to the underlying chat model — no re-setup required.

---

Configuring Access

From the admin panel

1. Go to Admin Panel → Digital Employees
2. Click Configure on the agent you want to restrict
3. Scroll to the User Access section at the bottom of the agent detail page
4. Use the access control panel to add users or groups:
   • Click Add User — search by name or email
   • Click Add Group — search by group name
5. Set permission to Read (users can chat with the agent)
6. Click Save Access

Changes take effect immediately — the agent is hidden from users who are not in the grants list.

---

Access Grant Examples

Restrict to a specific group

Add a single grant:

Principal Type	Principal	Permission
Group	HR Team	Read

All members of the HR Team group can chat with the agent. No other users can see it.

Restrict to multiple groups

Principal Type	Principal	Permission
Group	HR Team	Read
Group	HR Admins	Read

Both groups have access. Members of either group can chat with the agent.

Allow a specific external user

Principal Type	Principal	Permission
Group	HR Team	Read
User	alice@example.com	Read

HR Team members plus Alice individually can access the agent.

Open to all users (explicit wildcard grant)

Use a wildcard * principal to explicitly grant access to every user. This is useful when you want the grants list to be non-empty (for audit trail or API clarity) while still allowing all users:

Principal Type	Principal	Permission
User	*	Read

{
  "access_grants": [
    { "principal_type": "user", "principal_id": "*", "permission": "read" },
    { "principal_type": "user", "principal_id": "*", "permission": "write" }
  ]
}

This is equivalent to leaving the grants list empty — all users with chat access can interact with the agent. Use this pattern when programmatically seeding agents (e.g. via seed_agent.py) to make the intent explicit.

Alternatively, leave the grants list empty for the same effect.

---

Access Control via API

POST /api/v1/digital-employees/{agent_id}/access
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "access_grants": [
    {
      "principal_type": "group",
      "principal_id": "grp_hr_team_uuid",
      "permission": "read"
    },
    {
      "principal_type": "user",
      "principal_id": "usr_alice_uuid",
      "permission": "read"
    }
  ]
}

Response: Returns the updated agent model.

To open the agent to all users, send an empty array:

{ "access_grants": [] }

---

Access Persistence

Access grants are stored in two places:

1. Agent config (config.access_grants) — persisted in the digital_employee database table. These survive agent re-setup and server restarts.
2. Chat model (de_{slug}) — applied to the underlying model via the models access API. This is what the chat interface checks when showing the agent in the sidebar.

Both are kept in sync by the /access endpoint. When you re-run Setup, the grants from the agent config are automatically re-applied to the new model.

---

Tips

Use groups for scalability — Managing access by group is much easier than by individual user. When a new HR employee joins, add them to the HR Team group and they immediately get access to all HR-restricted agents.

Check group membership — Go to Admin Panel → Users → Groups to see and manage group members.

Test access as a user — After configuring grants, switch to a non-admin user account to verify the agent appears (or is hidden) as expected. Admin accounts bypass access restrictions.

Access does not affect Setup — Only admins can run Setup and Resync. Access grants only affect who can chat with the agent, not who can manage it.

---

Troubleshooting

Agent doesn't appear in the sidebar after granting access → The agent must have enabled = true. Check the toggle on the Digital Employees grid page.

Agent appears for all users even after adding grants → Verify the grants were saved (click Save Access, not just Save Config). The two buttons do different things.

A specific user can't see the agent → Check that:

1. The user or one of their groups is in the grants list
2. The ENABLE_DIGITAL_EMPLOYEES flag is true
3. The user has chat access (not pending or banned)

Grants are lost after re-running Setup → This should not happen — grants in config.access_grants are re-applied during Setup. If it does, re-save access after Setup completes.