Execution policies and role-based access

Every action has a policy answering three questions: who can trigger it, when it requires confirmation, and what role conditions apply.

Governance tiers

Automatic

The action runs immediately. Use for all read actions, lookups, and autocomplete calls the AI makes silently.

Confirm required

The AI prepares the full payload, then pauses. The user sees a confirmation panel before anything executes. Use for anything that creates, modifies, or deletes data.

When in doubt, use Confirm required. It costs the user one click. It prevents a category of mistakes that are expensive to undo.

Roles

Roles in Candu Actions are a product-layer guardrail: they decide which actions appear to a given user. They are not a security boundary. Your API must enforce its own access controls — Candu’s role check just prevents the AI from offering an action the user shouldn’t see in the first place.

How role-gating works

There is no separate role parameter. You pass the user’s role as a key inside the identifiers object at init() time:

window.canduAgentik.init({
  userId: "user-123",
  clientToken: "YOUR_CLIENT_TOKEN",
  snippetVersion: "0.2.0",
  identifiers: {
    role: "admin"   // matches role configured on each action
  }
});

Candu Actions compares the role value against the roles configured on each action in the dashboard. Users always have access to actions configured for Everyone regardless of their role. Actions configured for a specific role are only available when the identifier value matches.

Role	Who can trigger it
Everyone	All users, always
Manager	Users where `identifiers.role === "manager"`
Admin	Users where `identifiers.role === "admin"`

Role values are arbitrary strings — these are illustrative. Configure whichever role names match your app’s existing user types. If no role is passed, or the value doesn’t match any configured role, the user still has access to all Everyone actions. Role gating is evaluated per request. A user whose role changes mid-session will see the available actions update at their next message.

Identifiers

Identifiers are runtime context values you pass to Candu Actions at init() time. It’s a free-form key-value object — anything the AI might need at runtime that isn’t user-specific.

window.canduAgentik.init({
  userId: "user-123",           // required
  clientToken: "YOUR_TOKEN",    // required
  snippetVersion: "0.2.0",      // required
  identifiers: {                // optional
    role: "admin",
    organizationId: "org-456",
    workspaceSlug: "my-workspace"
  }
});

Beyond gating, identifiers do real work at runtime. Any key in the identifiers object is available as a {variable} in action endpoint templates — /api/{organizationId}/segments resolves at request time from identifiers.organizationId. This is how you keep action definitions tenant-agnostic. Identifiers are injected into the AI’s system prompt on every request. They are never written to any database — they’re request-scoped only and discarded when the request completes.

Data and privacy

Data	Persisted
`userId`	Yes — used to group runs in the Activity view
Identifiers	No — request-scoped only
User message text	Yes
Action inputs and outputs	Yes (as JSON)
Config files	Yes — retained until deleted

If your API returns sensitive data in a response body, that data will appear in execution logs. Design your action endpoints to return the minimum necessary response. See Execution & Logs for the full field reference.

​Governance tiers

​Automatic

​Confirm required

​Roles

​How role-gating works

​Identifiers

​Data and privacy

Governance tiers

Automatic

Confirm required

Roles

How role-gating works

Identifiers

Data and privacy